Trigger policies

A trigger policy decides when a node fires. It can be set on the CLI via --policy SPEC (on node create and node modify) or in source via a #[cerulion_node(...)] attribute. Trigger policy lives only on the macro side; graph YAML carries no policy block.

`--policy SPEC` grammar

Accepted forms:

SPEC	Behavior	Rules
`period_ms=N`	Fire every N ms.	N must be a positive integer > 0. Bare `period_ms` (no `=N`) → error “requires a value”. `period_ms=0` → error “must be > 0”.
`sync_window_ms=N`	Fire when all trigger inputs arrive within an N-ms window.	Same N rules.
`external`	Self-triggering ingress node: the node supplies its own readiness source (a file descriptor, a blocking call, or host-driven triggering).	Case-insensitive keyword. Rejected under `--time-source virtual`.
`data_trigger=NAME` or `trigger=NAME`	Fire when the named input receives a message.	NAME must be non-empty and match a declared input.
anything else	error	”unknown policy spec `X`” listing the accepted forms.

There is no default policy keyword — --policy default errors with “unknown policy spec”. A 100 ms period must be written --policy period_ms=100.

There is no deadline_ms policy spec — --policy deadline_ms=N errors with “unknown policy spec deadline_ms”. To watch for late data on a trigger input, use #[input(trigger, expect_within_ms = N)] in your node source.

Macro-attribute equivalents

Each --policy SPEC has an equivalent #[cerulion_node(...)] attribute. See Node macro reference for full attribute semantics.

`--policy SPEC`	Macro attribute
`period_ms=N`	`#[cerulion_node(period_ms = N)]`
`sync_window_ms=N`	`#[cerulion_node(sync_window_ms = N)]`
`external`	`#[cerulion_node(external)]`
`data_trigger=NAME` / `trigger=NAME`	field marked `#[input(trigger)]` named `NAME`

The unbounded_sync, tick_within_ms = N, and throttle_ms = N attributes have no --policy SPEC equivalent; they are macro-only. Write them into nodes/<type>/src/lib.rs yourself.

Defaulting matrix

When --policy is omitted, node create resolves the policy from the declared inputs:

Inputs declared	Result
0 inputs (no `-i`, no `-T`)	Error: source-only nodes must declare a non-data policy explicitly (`--policy period_ms=N` or `--policy external`).
1+ inputs via `-i` only	No node-level policy attribute is written. You then have to mark one input `#[input(trigger)]` in the source, or add a node-level policy — a node with ports and neither does not compile.
`-T` set	A data trigger on that input, regardless of the `-i` count.
Non-data `--policy` + `-T`	Error (conflict).

Policy short labels

node list and node info print a short policy label in their POLICY column:

Label	Policy
`period <N>ms`	Period
`sync <N>ms`	Bounded sync
`sync ∞`	Unbounded sync
`external`	External
`trigger:<input>`	Data trigger
`-`	None

Get started

Concepts

Guides

Studio and Hindsight

Reference

Community

`--policy SPEC` grammar

Macro-attribute equivalents

Defaulting matrix

Policy short labels

​--policy SPEC grammar

​Macro-attribute equivalents

​Defaulting matrix

​Policy short labels

`--policy SPEC` grammar

Macro-attribute equivalents

Defaulting matrix

Policy short labels