Throttle

The Throttle operation limits how often a path gets through. Given a stream of runs it lets one value past per window and drops the rest — either the first value of each window (Leading) or the last one (Trailing). Use it where a chatty producer would otherwise drive an expensive Node on every message.

Inputs

Port	Type	Required	Description
>	Any	No	Optional gate. When closed, the path stops and no value is recorded.
In	Any	Yes	The value to pass through. A Nil value fails the Node; its On Error verb resolves the failure.

Outputs

Port	Type	Default	Description
Out	Mirrors In	Nil	The value that got through this window. Takes the type of whatever is connected to In.

Properties

Name	Type	Default	Description
Window (seconds)	Integer	10	Length of the window, 1–2147483647.
Mode	Combo	Leading	Leading emits the first value of each window and drops the rest. Trailing collects and emits the last value when the window closes.
On Error	Combo	Stop this branch	Per-op On Error verb. A value Throttle cannot throttle never reaches the window, so the Editor offers it the two verbs that write nothing: Stop this branch / Continue with the last value. See the Error Handling guide.

State on Reload

Out is preserved across restarts. The window is not: after a restart the rate limit starts fresh, no timer is re-armed, and a value collected but not yet emitted in Trailing mode is dropped.

A value that gets through starts a new path

The path that feeds Throttle ends at it, in both modes. A value that gets through goes downstream on a new path that Throttle starts, in the same way Delay does — so nodes downstream of a Throttle run on that new path, not on the one that fed it.

The two modes differ only in when that happens: Leading starts the path as the value arrives, Trailing when the window closes.

---

How It Works

Leading

1. Gate check — if the Gate is connected and closed, the path stops here.

2. Inside a window? — if less than Window (seconds) has passed since the last value got through, the path stops and reports Throttle: value dropped inside the throttle window.

3. Emit — otherwise the window restarts from now, Out is written, and Throttle starts the path that carries the value downstream.

Trailing

1. Gate check — if the Gate is connected and closed, the path stops here.

2. Collect — the value replaces whatever was collected earlier this window. The arriving path always stops, reporting Throttle: trailing window armed; latest value emits when it closes.

3. Arm once — the first value of a window arms a timer for Window (seconds). Later values in the same window replace the collected value without touching the timer.

4. Emit — when the timer expires, Out is written with the last collected value and a new execution path begins.

---

Examples

Leading, 10 s window

Runs at t=0s, 1s, 2s, 12s:

t	In	Result
0 s	A	Out = A, new path begins
1 s	B	dropped
2 s	C	dropped
12 s	D	Out = D, new path begins

Trailing, 10 s window

Same runs:

t	In	Result
0 s	A	collected, timer armed, path stops
1 s	B	replaces A, path stops
2 s	C	replaces B, path stops
10 s	—	Out = C, new path begins
12 s	D	collected, timer armed, path stops

---

Use Cases

• Protecting a paid call — a sensor publishing every second need not drive a REST API Call every second. Leading reacts immediately and then holds off.
• Settling a noisy switch — Trailing waits for the flapping to stop and forwards the value it settled on.
• Rate-limiting notifications — one message per window, however many events arrived.

---

Error Handling

Throttle fails when In is unconnected or Nil, reporting Throttle: input is not connected or holds Nil; the Node’s On Error verb resolves the failure.

Verb	What it does
Stop this branch (default)	This Node and its dependents stop; Out keeps its value, and the Node’s last attempt reads as failed — the engine’s record of the Node, not a mark on the port.
Continue with the last value	The window stands as it was and no path is started; Out keeps its value, not stamped as new.

A value Throttle cannot throttle never reaches the window, so there is nothing for Continue with the fallback to write: putting one through would spend a window on a value nobody sent and start a path carrying it. Throttle’s schema states the two verbs above, and the Editor offers only those.

Dropping a value because the window is still open is not an error — it is a stop, and no verb is consulted.

---

Limitations

• The window is fixed at configuration time and cannot be driven from an input port.
• One value is carried per Node. To throttle several signals together, pack them with Report first, or use one Throttle per signal.
• Nothing about the window survives a restart, so the first run after one always gets through.