Skip to main content

AutonomousOperator

Trait AutonomousOperator 

Source
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>;
}
Available on crate feature 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 bodyits facethe sentence
bounded fan-out, a simple serial unitOperator / AsyncOperatorone 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’sStreamOperator / AsyncStreamOperatora 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 BOOKSAutonomousOperator / AsyncAutonomousOperatora 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

phasewhosewhat happens
constructionthe launch’s create walkPURE 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 slotthe launchthe value sits in the mount, moved nowhere, until an engine is put under it
ignitionthe launchthe value MOVES onto the thread that hosts it — one move, one owner, for the node’s whole life
startupthe noderun’s PROLOGUE: spawn the workers, open the internal queues, destructure self’s parts into them
the loopthe nodeselect, gate, batch, route, publish, answer acks — all of it
teardownthe noderun’s EPILOGUE, and it is EXPLICIT: close the in-queues, let the workers drain their session tails, join them, then answer the Fin
the backstopDropidempotent, 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 happenedwhat run answers
every upstream hung up and drainedOk(Fin::Spent)
heard the stop and wound downOk(Fin::Stopped)
DIED — it neither finished nor was stoppedErr(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 future

Required Associated Types§

Source

type In

The message this node consumes — the declared struct an edge moves.

Source

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.

Source

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§

Source

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".

Implementors§