Crate embassy_supervisor

Expand description

Dependency-ordered task-lifecycle supervision for embassy firmware.

embassy-supervisor brings tasks up in dependency order, supervises their lifecycle (Terminate, Pause, OnDemand), tears dependents down before the things they depend on, and verifies declared dataflow against live behaviour. The graph is declared through the supervisor_graph! macro (re-exported from embassy-supervisor-macros) and checked at compile time.

The crate is HAL-agnostic, no_std, and has no allocator or board-specific dependencies.

Modules§

shape: Structural facts about a graph, as bits in Topology::SHAPE — what the graph contains, decided at supervisor_graph! expansion and carried in the topology’s type, so lifecycle code serving an absent structure is
trace: Runtime tracing hooks and task introspection helpers.

Macros§

compose_graph: Compose a graph out of one or more supervisor_fragment! declarations.
supervisor_fragment
supervisor_graph

Structs§

Aborted: The shutdown side of TaskNode::run_cancellable’s result: the raced work future was cancelled at its await point because a stop/pause request won the select. Pairs naturally with the exit: slot — a worker returning Result<R, Aborted> records completed-vs-cancelled for whoever reads the exit value.
Backed: A signal whose producer is started by the first reader that calls open. The value is not handed out until the producer is running and ready. The gate counts readers so the producer can retire once none are left (unwatched, TaskNode::retire).
Budget: A budget of u32 units divided among N claimant slots.
Claimant: A holder’s handle on one slot of a Budget: what a divisible entry hands the worker. Copy, so a worker may keep one per loop it runs.
ControlCommand: A control request addressed to a specific node.
ControlQueueFull: The control mailbox was full (4 outstanding requests) and the request was not enqueued. Returned by try_request_control; retry after the supervisor’s driver loop has drained a command, or use the awaiting request_control from async contexts.
Coupling: A declared read/write coupling between a node and a signal.
DeferredShrink: A scaling policy that grows immediately but shrinks only after a cooldown.
ElasticPool: An elastic pool backed by a ScalingPolicy.
FairShare: Every holder gets its want when the capacity covers the sum; otherwise the capacity is split in proportion to the wants, with the integer remainder handed one unit at a time to the lowest slots that can use it. Changes apply immediately in both directions.
Flat: The Topology of a graph with no deps: edges anywhere: zero-sized, every dep list is empty by type, and the topological order is declaration order. The walks a Supervisor runs over it fold to plain index loops, and the dependency cascades (activate, deactivate, restart) collapse to their seed sets.
Graph: A static task graph: the nodes, the topology over them, and optional pools.
GraphRef: A reference to a registered graph, used for runtime introspection.
Graphs: Iterator over registered graphs returned by graphs.
HealthEvent: One observation from Supervisor::monitor, delivered through wait_health.
Lease: A live claim on a Leased signal: the producer’s drain does not return until every Lease has been dropped.
Leased: A signal-like value whose producer can wait until all outstanding readers finish.
NodeCfg: The immutable half of a TaskNode: everything the graph declared about the node, none of what happens to it at runtime. No interior mutability, so the static carrying it lives in flash (.rodata); the RAM-resident node points at it. Built const with new plus the chainable with_* methods, exactly as supervisor_graph! emits it.
NodeFault: A node-scoped lifecycle failure: which node, and what went wrong.
Observer: A callable that returns a signal’s change count for observation.
Open: A reader’s hold on a Backed signal, from open. Deref gives the wrapped signal’s API; dropping the guard lets the producer notice the last reader has left.
Ordered: A Topology whose nodes are topologically sorted by their deps: edges.
PoolStats: Snapshot of an elastic pool’s current load.
ResourceSlot: A one-value handoff cell threading an owned resource from main into a supervised task — the safe replacement for Peripherals::steal() inside the task body.
Resumed: The pause side of TaskNode::run_pausable’s result: a stop/pause request won the race, the combinator acked and parked, and the supervisor has since resumed the node. By the time a body sees Err(Resumed) the park is already over — the next loop iteration is the fresh cycle.
ShrinkFastGrowSlow: FairShare’s division, applied asymmetrically: a cut lands at once, an increase is ramped at most step units per interval. The safety shape of a shared power or bandwidth budget — a holder must never be granted more than the budget can carry, so reductions cannot wait, while a holder drawing more can wait for the others to have backed off.
Sig: A typed handle to a signal declared in a reads:/writes: list.
SpawnerSlot: Runtime-filled slot holding a foreign executor’s SendSpawner.
Stamped: A signal wrapper that stamps every write with the time it happened, so a reader can ask how old the value is.
Supervisor: Orchestrates a set of managed tasks across spawn / teardown / bring-up.
TaskHandle: Coordination state for one task. Embedded inside TaskNode.
TaskNode: A node in the supervisor’s task graph.
Veto: One writer’s handle on its slot of a VetoGate, from TaskNode::veto.
VetoGate: A gate that is asserted while any of its N contributors holds it and released only once all of them have let go.

Enums§

ControlOp: A control request issued to the supervisor for a node.
Fault: A fault injected into a node through TaskNode::inject. The verbs act on the task, not the worker.
FaultKind: What went wrong in a NodeFault.
HealthKind: What the monitor observed about a node.
InjectError: Why TaskNode::inject refused.
Mode: Lifecycle policy for a managed task: what the task does on shutdown and what the supervisor does to bring it back.
PoolAction: Action the supervisor should take for a pool member.
ScaleAction: Decision an elastic scaling policy can return.

Traits§

BudgetPolicy: How a Budget’s capacity is divided over its holders’ wants.
CouplingPoint: A signal a node declares it reads or writes.
Divisible: The object-safe view of a Budget a Claimant and a node’s claims table go through, so neither names N.
Gated: A signal whose producer must be running and ready before a reader can use it.
Observable: A type whose writes can be observed without interpreting the value.
Pool: Object-safe, synchronous pool interface so &dyn Pool needs no heap: the policy decides here; the supervisor performs the async start/stop. Object-safe, synchronous pool interface used by the supervisor.
ResourceGate: Type-erased readiness view of a ResourceSlot, for the supervisor’s bring-up wait.
ScalingPolicy: Policy that decides when an elastic pool should grow or shrink.
Sink: A signal that can be written through the supervisor’s put verb.
Source: A signal that can be read through the supervisor’s get verb.
Topology: Structural information about a graph, used by Supervisor to decide which lifecycle code paths can be compiled out.
Zeroable: Trait for types that can be safely created with zeroed.

Functions§

graphs: Return an iterator over every registered graph, most recent first.
init_host_logging: Call once from a simulator’s or test’s main before the supervisor starts; records emitted earlier are dropped by the log facade. Errors if a logger is already installed — including a second call — in which case the existing logger and level are left untouched.
producer_of: Find the node that writes to entry, if there is exactly one.
request_control: Enqueue a control request, waiting for mailbox capacity if it is full. Lossless — the request is delivered once the supervisor’s driver loop drains an earlier command. Called by the application’s control surface.
request_scale: Signal that an elastic pool should re-evaluate its scaling decision.
try_request_control: Non-blocking variant of request_control for sync contexts (ISRs, callbacks). Fails with ControlQueueFull instead of dropping the request when the mailbox is full — the caller decides whether to retry or surface it.
try_wait_health: Non-blocking wait_health, for a consumer that polls (a status endpoint draining pending events, an existing loop that must not park here).
wait_bind: Await the next readiness transition of any node. The supervisor’s driver loop selects this alongside pool scaling and control.
wait_control: Await the next control request. Selected by the supervisor’s driver loop against pool scaling and any other application wake sources.
wait_health: Await the next health observation from Supervisor::monitor.
wait_scale: Wait until something requests a pool scaling re-evaluation.

Attribute Macros§

dataflow
dataflow_bundle