pub trait AutonomousOperator: Sized {
type In;
type Out: 'static;
type Error;
// Required method
fn run(
self,
ctx: Context,
upstreams: Upstreams<Self::In>,
downstream: Downstream<Self::Out>,
) -> Result<Fin, Self::Error>;
}runtime only.Expand description
A node whose WHOLE LIFE is one call: it owns the loop, selects across its own inbound edges in its own order, and publishes through its own downstream set until it is spent or told to stop.
§THE FACE-SELECTION LAW — three rows, and each has real residents
The pair above and the pair before it are both PER-DELIVERY faces: the framework runs the loop, hands the body one delivery at a time and keeps the books. This face hands the loop over. The three rows are one sentence each, and the question is what the NODE has to own:
| the body | its face | the sentence |
|---|---|---|
| bounded fan-out, a simple serial unit | Operator / AsyncOperator | one delivered item in, a handful of emissions out, and the framework drives every part of it |
| one delivery is one WHOLE LIFE where per-delivery parallelism AND fate bookkeeping are the FRAMEWORK’s | StreamOperator / AsyncStreamOperator | a demux: N warm bodies, an admission bound, a feed cut per delivery, the dead-letter kept by the lane |
| the node takes the wheel and KEEPS THE BOOKS | AutonomousOperator / AsyncAutonomousOperator | a decoder, a resampler, a conform, a heavy embedder: select order, arm priority, intake gating, batching, ack timing and internal workers are all the node’s |
The rows are PEERS rather than a ladder, exactly as the first two already are. A face is chosen
per node, the async axis cuts across all three unchanged, and no body already written moves.
§What the OPERATIONAL SPACE is, and why a third kind rather than a wider protocol
Operator::accept is called once per delivery and returns, so everything about WHEN the next
delivery is taken belongs to the driver: which upstream is read first, whether an upstream is
read at all this pass, how long the body parks between passes, when an input’s ack is released.
A body that needs any of those — a decoder holding per-track state that must drain its own
workers before admitting more work, a resampler that must not take a second track’s frames while
the first is mid-flush — cannot express it at that face, and changing accept’s protocol was
refused long ago on the count that decides it: 105 accept bodies in this tree, and a protocol
change is a change to every one of them.
So the answer is a THIRD KIND rather than a widened first. The framework still knows only WHAT nodes exist and HOW they connect, which is its founding division: the threads, the routing and the fan-out inside a node are the node’s own, and this face is where a node says so.
§What a run is handed
fn run(self, ctx: Context, upstreams: Upstreams<Self::In>, downstream: Downstream<Self::Out>)
-> Result<Fin, Self::Error>;Upstreams is the node’s inbound edges RAW — one receiving end per edge, in
declaration order — so a body puts a framework edge and a channel of its own into ONE select.
Downstream is the same out-edge set every other face publishes through,
handed whole. [ShutdownSignal] is the one thing the framework ever says to a body that is inside run
for its whole life.
§self BY VALUE, which is Source::run’s shape and its reason
There is nothing after it. A node of this kind is started ONCE and what it owns it owns until it
answers, so the value is MOVED into the call rather than borrowed for it — exactly as an origin’s
life takes its own. StreamOperator::run takes &mut self because there genuinely IS
something after it: the instance stays warm for the next delivery. Here there is no next.
The dividend is the prologue. A body that owns self can take itself APART into its workers
— a model handle onto one thread, a scratch arena onto another, a decoder table split by track —
which a &mut self body could only clone or lock. The parts move; nothing is shared that does
not have to be.
§THE LIFECYCLE, and every phase of it belongs to somebody nameable
| phase | whose | what happens |
|---|---|---|
| construction | the launch’s create walk | PURE DATA. No thread, no channel, no worker: a built-and-unignited node holds no live resource, so dropping one in its slot is a no-op |
| the slot | the launch | the value sits in the mount, moved nowhere, until an engine is put under it |
| ignition | the launch | the value MOVES onto the thread that hosts it — one move, one owner, for the node’s whole life |
| startup | the node | run’s PROLOGUE: spawn the workers, open the internal queues, destructure self’s parts into them |
| the loop | the node | select, gate, batch, route, publish, answer acks — all of it |
| teardown | the node | run’s EPILOGUE, and it is EXPLICIT: close the in-queues, let the workers drain their session tails, join them, then answer the Fin |
| the backstop | Drop | idempotent, and it is there so a PANIC-unwind cannot deadlock — see below |
Construction being pure data is a CONTRACT and not an observation. The launch builds every
node before it wires any of them and may refuse in between; a construction that had already
spawned a thread would leave one running behind a refusal nothing could unwind, because the
pre-ignition unwind consumes values and cannot join threads. So the threads start in run and
nowhere else, and a node in its slot is a bag of options and handles.
The teardown is the epilogue and the Drop is the backstop. An orderly wind-down is
spelled by the body: closing the in-queue senders is what tells a worker parked on a receive
that its stream is over, so it drains whatever session tail it holds, returns, and is joined. A
Drop impl that closes those same senders is what makes the same thing happen when the body
does NOT reach its epilogue — a panic unwinding through run drops the node’s parts, the
senders go, the parked workers wake and return, and a join on that path terminates instead of
waiting forever on a queue nobody will ever fill. Close before you join, in both places, and
the two paths agree.
Err DRAINS THE SAME WAY. A death is not a licence to abandon a worker mid-session: the
epilogue runs, the tails are drained, the workers are joined, and only then does the error go
back to be dead-lettered. What differs between the two exits is which arm of the Result is
answered and nothing else.
A respawn is a FACTORY REBUILD. Nothing reuses the husk of a node that ended — the value was
consumed by run and its workers are gone — so what a supervisor would restart is a fresh
construction from the same options. That is what makes the pure-data contract above worth
keeping: a rebuild is cheap exactly because construction touches nothing live.
§The ACK VOCABULARY IS UNCHANGED, and the only novelty is WHO answers
A Delivery taken off an edge carries its Custody exactly as it does
anywhere else, and the node answers it with an Ack exactly as a
Resident does — under the same AckMode its declaration
stated, with the same healing window behind Local. Nothing about the
protocol changes at this face. What changes is that the node’s own code says when.
§The ENDINGS are the origin layer’s, reused verbatim
| what happened | what run answers |
|---|---|
| every upstream hung up and drained | Ok(Fin::Spent) |
| heard the stop and wound down | Ok(Fin::Stopped) |
| DIED — it neither finished nor was stopped | Err(Self::Error) |
Err is a WHOLE-NODE death and not a per-delivery one, which is this face’s item read honestly:
the node’s item is its life. The party settles either way — a dead body is a finished body — and
the ending reaches the arrangement’s taps as Processed for both
endings and Failed for the death. Nothing restarts it, for the
reason the origin layer’s own note gives: a restart policy is a real design and every one of its
questions is answered differently by a decoder, a socket loop and a directory walk.
§Send, and this face asks for nothing
Operator’s law verbatim: mobility belongs to the engines. An autonomous node runs on a
thread of its own — the awaited half PINNED there, exactly as an origin’s is — so a !Send body
is an ordinary citizen here and no bound is written at the contract.
§Examples
use ingraph::{Context,
Ack, AutonomousOperator, Downstream, Fin, Lifecycle, ShutdownSignal, Upstreams, Wake, conduit,
};
/// A node that keeps its own books and its own crew: it spawns a worker in the prologue, feeds
/// it, answers each delivery's custody at a time of its own choosing, and winds the crew down
/// in the epilogue.
struct Counting {
/// Handed to the worker in the prologue — the by-value dividend, moved rather than shared.
label: String,
}
/// Closing the in-queue is what wakes a parked worker, so the drop is the idempotent backstop
/// under the epilogue: a panic unwinding through `run` still lets the join terminate.
struct Crew {
jobs: Option<conduit::Sender<u64>>,
hand: Option<std::thread::JoinHandle<usize>>,
}
impl Crew {
/// Close, THEN join — the one order both the epilogue and the drop keep.
fn wind_down(&mut self) -> usize {
drop(self.jobs.take());
self.hand.take().map_or(0, |hand| hand.join().unwrap_or(0))
}
}
impl Drop for Crew {
fn drop(&mut self) {
let _ = self.wind_down();
}
}
impl AutonomousOperator for Counting {
type In = u64;
type Out = u64;
type Error = core::convert::Infallible;
fn run(
self,
ctx: Context,
upstreams: Upstreams<u64>,
_downstream: Downstream<u64>,
) -> Result<Fin, Self::Error> {
// THE PROLOGUE: the queues are opened and `self`'s parts move INTO the crew.
let (jobs, to_do) = conduit::bounded::<u64>(8);
let label = self.label;
let hand = std::thread::spawn(move || {
let mut seen = 0;
while to_do.recv().is_some() {
seen += 1;
}
let _ = label;
seen
});
let mut crew = Crew { jobs: Some(jobs), hand: Some(hand) };
// THE LOOP, and every decision in it is this node's.
let fin = loop {
if ctx.shutdown().is_shutdown() {
break Fin::Stopped;
}
for wake in upstreams.drain(0) {
let Wake::Delivered(delivery) = wake else {
continue;
};
let (payload, custody) = delivery.into_parts();
let released = payload.keys().copied().collect();
for item in payload {
let _ = crew.jobs.as_ref().map(|jobs| jobs.send(item.into_value()));
}
// The books, kept by the node: the keys it is done with, released when it says so.
if let Some(custody) = custody {
custody.send(Ack::new(released, "counting", Lifecycle::Processed(())));
}
}
if upstreams.is_spent() {
break Fin::Spent;
}
};
// THE EPILOGUE: close the in-queue, let the worker drain its tail, join it, THEN answer.
let _counted = crew.wind_down();
Ok(fin)
}
}The answer is a Fin and NOT a future, which is what this half of the pair buys — the same
fact Operator states two traits up:
use ingraph::{AutonomousOperator, Downstream, Fin, ShutdownSignal, Upstreams};
let _ = unit.run(ctx, up, down).await; // a `Result` is not a futureRequired Associated Types§
Sourcetype Out: 'static
type Out: 'static
The message it publishes — the declared struct an edge moves.
'static, per StreamOperator::Out’s reason read at this kind: what a downstream set
carries outlives the call that made it, and this call is the node’s whole life.
Sourcetype Error
type Error
What a life that DIED refuses with. Bound-free here, for Operator::Error’s reason, and it
is the carrier of the failure scene — the node’s own account of what killed it.
Required Methods§
Sourcefn run(
self,
ctx: Context,
upstreams: Upstreams<Self::In>,
downstream: Downstream<Self::Out>,
) -> Result<Fin, Self::Error>
fn run( self, ctx: Context, upstreams: Upstreams<Self::In>, downstream: Downstream<Self::Out>, ) -> Result<Fin, Self::Error>
RUN — the node’s whole life, owning the loop.
It keeps the BARE name AsyncAutonomousOperator::run also carries, for
Operator::accept’s measured reason: a body that imports one face writes run with no
ceremony, and a type wearing BOTH is E0034 naming the two candidates and offering the
disambiguating spelling. The name is StreamOperator::run’s and
Source::run’s too, and that costs nothing — they are different traits,
disambiguated by the same spelling.
§Errors
Whatever this node’s own life refuses with — a body that DIED rather than ending. Both endings
are Ok, and the trait’s own table is where the three outcomes are set beside each other.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".