This commit is contained in:
2026-10-13 10:02:20 +02:00
parent a93f865e91
commit 80e595c02e
24 changed files with 2210 additions and 4310 deletions
+32 -51
View File
@@ -1,75 +1,56 @@
# Keeping state in a flow
Logic nodes are pure functions of their inputs. There is no `context`, no
`global`, no handle to a store. A node is called with the values of the
messages it declares and returns the values of the messages it provides.
Need a running total or a last-seen value? Make it a message. Function nodes
have no hidden `context` or global flow store.
That is deliberate: a node with hidden state cannot be run twice in parallel,
cannot be replayed, and cannot be moved to another worker. But plenty of real
automations need to remember something. This is how.
## Read and write the same message
## State is a message the node both reads and writes
A running total, a debounce timer, a last-seen reading: each is a value that
survives between runs. Give it a message name, declare it as both an input and
an output, and it is state:
Declare `reading` and `total` as inputs, and `total` as an output:
```python
def process(reading, total=0.0):
def process(reading, total):
return {"total": total + reading}
```
with `reading` and `total` as inputs and `total` as the output. Each run reads
the total the previous run wrote.
Add `total` to the flow's **Inputs** with a starting value of `0.0`. Each
execution reads the previous total and publishes the next one.
Two things make this work rather than loop forever:
- A node is never downstream of itself, so its own publication does not run
it again.
- A triggering input needs a starting value. Without one, validation reports
`self_loop_needs_initial`; a Python default alone does not supply the message.
- **A node never depends on itself.** The graph is built from message names, but
a node providing a message it also requires is not placed downstream of
itself. Publishing `total` does not re-run the node that wrote it.
- **The value must start somewhere.** The first run has nothing to read. Declare
the message as a flow input with a starting value; otherwise the flow reports
`self_loop_needs_initial` at edit time and refuses to publish.
## Feedback between two nodes
The port needs a default in the function signature (`total=0.0` above) so the
first call is well-formed even if the value is missing.
## Feeding a value back between two nodes
Sometimes the value comes from a different node, such as a controller reading back what
an estimator computed from its own last output. Written plainly that is a cycle,
and the validator rejects it, because a graph where A waits for B and B waits
for A can never start.
What is actually meant is that the fed-back value is *state*, not a trigger.
Say so, by marking the input non-triggering:
A controller may read an estimate that depends on its own previous output.
Ordinary triggering inputs would form a cycle. Mark the feedback input
**non-triggering** in the flow definition instead:
```json
{"name": "estimate", "port": "estimate", "dtype": "float", "trigger": false}
```
A non-triggering input:
It creates no dependency and does not wake the node. Whenever another input
runs the node, it reads the latest estimate. If no estimate exists yet, that
argument is omitted, so give it a Python default:
- creates no dependency, so it cannot form a cycle;
- never makes the node wait. If the message has no value yet, the port is
simply left out of the call, and the function's default applies;
- is read fresh from state whenever the node does run, for whatever reason.
```python
def process(reading, estimate=0.0):
return {"command": reading - estimate}
```
Use it for the back edge only. An input that should wake the node is an ordinary
input, and marking it non-triggering would mean the node never runs at all.
Use this on the feedback input; keep the inputs that should wake the node
triggering. Configure `trigger` through the API or flow JSON; the node panel
does not currently expose it.
## What still holds engine-side state
## Built-in state
Built-in nodes that are *about* time or change (rate limiting, filter-on-change,
delay, cron) keep what they need in the engine's own state backend, under keys
that never appear as messages. That is the engine's business, not a flow's: the
line is that node *code* you write never reaches for state, while node *types*
the engine ships may.
Storage and direct-I/O nodes are the other sanctioned exception, since talking
to a device or a database is stateful by nature.
Built-in nodes such as delay, rate limit and filter-on-change keep their own
timing or comparison state in the engine. Storage and device nodes also manage
the state needed for their connections. Your Function code still exchanges
state through declared messages.
## See also
- [Where a node's values come from](values.md) — ports, settings and flow inputs
- [Node types](../reference/node-types.md) — the built-ins that do keep engine-side state
- [Where a node's values come from](values.md)
- [Node types](../reference/node-types.md)