Struct Supervisor 

pub struct Supervisor<E: Event, T: Topic<E> = DefaultTopic> { /* private fields */ }

Coordinates actors and the broker, and owns the top-level runtime.

Actor Registration

// Subscribe to specific topics
supervisor.add_actor("processor", |ctx| Processor::new(ctx), &[MyTopic::Data])?;

// Subscribe to all topics (e.g., monitoring)
supervisor.add_actor("monitor", |ctx| Monitor::new(ctx), Subscribe::all())?;

// Subscribe to no topics (pure event producer)
supervisor.add_actor("producer", |ctx| Producer::new(ctx), Subscribe::none())?;

Runtime Control

• start() spawns the broker loop and returns immediately (non-blocking).
• send(event) emits events into the broker.
• run() combines start() and join(). Consumes the supervisor.
• join() awaits all actor tasks to finish. Consumes the supervisor.
• stop() graceful shutdown. Consumes the supervisor.

The terminal methods (run, join, stop) take ownership of the supervisor, preventing use-after-shutdown at compile time.

See also: Actor, Context, Topic.

Implementations

impl<E: Event, T: Topic<E>> Supervisor<E, T>

pub fn new(config: SupervisorConfig) -> Self

Create a new supervisor with the given runtime configuration.

pub fn add_actor<A, F, S>( &mut self, name: &str, factory: F, topics: S, ) -> Result<ActorId>

where A: Actor<Event = E>, F: FnOnce(Context<E>) -> A, S: Into<Subscribe<E, T>>,

Register a new actor with a factory that receives a Context<E>.

This is the primary way to register actors with the supervisor.

Arguments

• name - Actor identifier used for metadata and routing
• factory - Closure that receives a Context and returns the actor
• topics - Slice of topics the actor subscribes to

Errors

Returns Error::DuplicateActorName if an actor with the same name is already registered. Returns Error::BrokerAlreadyStarted if called after start().

Example

supervisor.add_actor(
    "processor",
    |ctx| DataProcessor::new(ctx),
    &[MyTopic::Data, MyTopic::Control]
)?;

pub fn build_actor<'a, A, F>( &'a mut self, name: &str, factory: F, ) -> ActorBuilder<'a, E, T, A>

where A: Actor<Event = E>, F: FnOnce(Context<E>) -> A,

Start building an actor registration with custom configuration.

Returns an ActorBuilder that lets you set topics, channel capacity, or a full ActorConfig before calling build().

Use this instead of add_actor when you need per-actor settings that differ from the global defaults.

Example

sup.build_actor("consumer", |ctx| Consumer::new(ctx))
    .topics(&[Topic::Data, Topic::Command])
    .channel_capacity(512)
    .build()?;

pub async fn send<IE: Into<IntoEnvelope<E>>>(&self, into_envelope: IE) -> Result

Emit an event into the broker from the supervisor.

Errors

Returns Error::MailboxClosed if the broker channel is closed.

pub async fn run(self) -> Result

Convenience method to start and then await completion of all tasks. Blocks until shutdown.

Errors

Propagates any error from start() or join().

pub async fn start(&mut self) -> Result

Start the broker loop in a background task. This returns immediately.

Errors

Currently infallible, but returns Result for forward compatibility.

pub async fn join(self) -> Result

Waits until at least one of the actor tasks completes then triggers a shutdown if not already requested.

Errors

Returns Error::Internal if an actor task panics. Propagates any error returned by stop().

pub async fn stop(self) -> Result

Request a graceful shutdown, then await all actor tasks.

Shutdown Process

1. Waits for the broker to receive all pending events (up to 10 ms)
2. Sends StopBroker command and waits for the broker to drain actor queues
3. Sends StopRuntime command and waits for all actor tasks to complete

Errors

Returns Error::Internal if an actor task panics during shutdown.

pub fn config(&self) -> &SupervisorConfig

Returns the supervisor’s configuration.

pub fn monitors(&mut self) -> &mut MonitorRegistry<E, T>

Available on crate feature monitoring only.

Returns the monitor registry for adding, removing, and controlling monitors.

impl<E: Event, T: Topic<E> + Label> Supervisor<E, T>

pub fn to_mermaid(&self) -> String

Generate a Mermaid flowchart showing actor subscriptions.

Topics are shown as circles, actors as boxes. Arrows indicate that an actor subscribes to (receives events from) a topic.

Actors with Subscribe::all() are connected to all known topics. Actors with Subscribe::none() appear isolated (no incoming arrows).

Example output

flowchart LR
    SensorData((SensorData)) --> processor
    SensorData --> logger
    Alert((Alert)) --> logger

Topic names are obtained via Topic::name().

impl<E: Event, T: Topic<E> + Label> Supervisor<E, T>

pub fn to_json(&self) -> Result<String>

Available on crate feature serde only.

Export actor subscription topology as JSON.

This method provides a machine-readable representation of which actors are subscribed to which topics. It mirrors the information shown by to_mermaid, but returns structured JSON suitable for inspection, tooling, or testing.

The output is a flat list where each entry contains:

• actor_id - the actor name
• subscriptions - topic labels the actor receives events from

Semantics

• Actors registered with Subscribe::all() are expanded to include all known topics discovered from explicit subscriptions.
• Actors registered with Subscribe::none() produce an empty list.
• Topic names are obtained via Label::label().

This export reflects declared routing configuration only. It does not represent runtime message flow, event producers, or supervision hierarchy.

Errors

Returns any serialization error produced by serde_json.

Example

let json = supervisor.to_json()?;
println!("{json}");

Trait Implementations

impl<E: Event, T: Topic<E>> Debug for Supervisor<E, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: Event, T: Topic<E>> Default for Supervisor<E, T>

fn default() -> Self

Returns the “default value” for a type.