Document the cascade guarantee and the cascade ceiling

A node runs when something it reads was published, not merely when something
upstream of it ran — worth saying now that it is true, since it is what a
reader relies on when a rate-limited port goes quiet. Plus `FLOW_MAX_CASCADES`
in the engine's configuration table.
This commit is contained in:
2026-08-26 10:27:23 +02:00
parent 7794a2a021
commit 67c297958b
2 changed files with 5 additions and 0 deletions
+4
View File
@@ -27,6 +27,10 @@ being explicit about the consequences:
- **Fan-in is free.** Two nodes providing `temperature` are two producers of - **Fan-in is free.** Two nodes providing `temperature` are two producers of
one message. The consumer does not change. one message. The consumer does not change.
- **A node runs when something it reads was published.** Not merely when
something upstream of it ran: a node that produced nothing this time — held
back by a rate limit, say — leaves what reads it on the value it already
has, and so does everything behind that.
- **A wire cannot be wrong.** There is no wire. There is a name that either - **A wire cannot be wrong.** There is no wire. There is a name that either
matches or does not, and the canvas tells you at edit time which it is. matches or does not, and the canvas tells you at edit time which it is.
- **Layout is not a document.** The canvas computes the arrangement, so a flow - **Layout is not a document.** The canvas computes the arrangement, so a flow
+1
View File
@@ -123,6 +123,7 @@ warning into a refusal to start.
| Variable | Default | Notes | | Variable | Default | Notes |
|---|---|---| |---|---|---|
| `FLOW_MAX_WORKERS` | `4` | node-code subprocesses run in parallel | | `FLOW_MAX_WORKERS` | `4` | node-code subprocesses run in parallel |
| `FLOW_MAX_CASCADES` | `4` | cascades in flight at once; throughput is this over the mean cascade time, so raise it where nodes wait on a network rather than a CPU |
| `FLOW_NODE_TIMEOUT` | `0` | seconds a node may be silent, unless it sets its own; 0 is no limit | | `FLOW_NODE_TIMEOUT` | `0` | seconds a node may be silent, unless it sets its own; 0 is no limit |
| `OBS_RETENTION_DAYS` | `30` | how long metrics, events and run records are kept | | `OBS_RETENTION_DAYS` | `30` | how long metrics, events and run records are kept |