docs
This commit is contained in:
+32
-51
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user