Struct Supervisor 

pub struct Supervisor;

Supervisor runtime entry point.

Implementations

impl Supervisor

pub async fn start( spec: SupervisorSpec, ) -> Result<SupervisorHandle, SupervisorError>

Starts a supervisor runtime from an owned specification value.

Arguments

• spec: Supervisor specification owned by the caller.

Returns

Returns a SupervisorHandle connected to the runtime control loop.

Examples found in repository

examples/supervisor_quickstart.rs (line 21)

async fn main() -> ExampleResult {
    // Load centralized YAML configuration.
    let state = load_config_state("examples/config/supervisor.yaml")?;
    // Derive the supervisor specification from configuration.
    let spec = state.to_supervisor_spec()?;
    // Start the supervisor runtime from the specification.
    let handle = Supervisor::start(spec).await?;
    // Query the current runtime state.
    let current = handle.current_state().await?;
    // Print the current state for the learner.
    println!("{current:#?}");
    // Use the runtime handle for the shutdown request.
    handle
        // Request tree shutdown with audit metadata.
        .shutdown_tree("operator", "quickstart complete")
        // Wait for the shutdown command result.
        .await?;
    // Finish the example successfully.
    Ok(())
    // End the quickstart example.
}

examples/observability_probe.rs (line 21)

async fn main() -> ExampleResult {
    // Load centralized YAML configuration.
    let state = load_config_state("examples/config/supervisor.yaml")?;
    // Derive the supervisor specification from configuration.
    let spec = state.to_supervisor_spec()?;
    // Start the supervisor runtime from the specification.
    let handle = Supervisor::start(spec).await?;
    // Subscribe to runtime event text.
    let mut events = handle.subscribe_events();
    // Query the current runtime state.
    let current = handle.current_state().await?;
    // Print the current state for the learner.
    println!("current={current:#?}");
    // Read one emitted runtime event when it is available.
    let received = events.recv().await;
    // Continue only when an event was received.
    if let Ok(event) = received {
        // Print the observed runtime event.
        println!("event={event:#?}");
        // Finish the optional event display.
    }
    // Use the runtime handle for the shutdown request.
    handle
        // Request tree shutdown with audit metadata.
        .shutdown_tree("operator", "observability probe complete")
        // Wait for the shutdown command result.
        .await?;
    // Finish the example successfully.
    Ok(())
    // End the observability example.
}

examples/shutdown_tree.rs (line 23)

async fn main() -> ExampleResult {
    // Load centralized YAML configuration.
    let state = load_config_state("examples/config/supervisor.yaml")?;
    // Derive the supervisor specification from configuration.
    let spec = state.to_supervisor_spec()?;
    // Start the supervisor runtime from the specification.
    let handle = Supervisor::start(spec).await?;
    // Build the visible shutdown phase list.
    let phases = [
        // Show the stop request phase.
        ShutdownPhase::RequestStop,
        // Show the graceful drain phase.
        ShutdownPhase::GracefulDrain,
        // Show the abort stragglers phase.
        ShutdownPhase::AbortStragglers,
        // Show the final reconcile phase.
        ShutdownPhase::Reconcile,
        // Finish the shutdown phase list.
    ];
    // Iterate over the visible shutdown phases.
    for phase in phases {
        // Print each planned phase.
        println!("planned phase={phase:#?}");
        // Finish the phase display loop.
    }
    // Use the runtime handle for the shutdown request.
    handle
        // Request tree shutdown with audit metadata.
        .shutdown_tree("operator", "shutdown tree example")
        // Wait for the shutdown command result.
        .await?;
    // Finish the example successfully.
    Ok(())
    // End the shutdown example.
}

examples/runtime_control_story.rs (line 25)

async fn main() -> ExampleResult {
    // Load centralized YAML configuration.
    let state = load_config_state("examples/config/supervisor.yaml")?;
    // Derive the supervisor specification from configuration.
    let spec = state.to_supervisor_spec()?;
    // Start the supervisor runtime from the specification.
    let handle = Supervisor::start(spec).await?;
    // Subscribe to runtime event text.
    let mut events = handle.subscribe_events();
    // Build the child identifier used by operator commands.
    let child_id = ChildId::new("market_feed");

    // Send an add child command through the control handle.
    let add = handle
        // Add a manifest under the root supervisor.
        .add_child(
            // Target the root supervisor.
            SupervisorPath::root(),
            // Provide the child manifest text.
            "id=market_feed kind=AsyncWorker readiness=Explicit",
            // Provide the requesting actor.
            "operator",
            // Provide the audit reason.
            "attach market feed during incident rehearsal",
            // Finish the add child arguments.
        )
        // Wait for the add child command result.
        .await?;
    // Print the add child result.
    print_result("add_child", add);

    // Print the pause child result.
    print_result(
        // Label the pause result.
        "pause_child",
        // Send the pause child command.
        handle
            // Pause automatic governance.
            .pause_child(child_id.clone(), "operator", "stop automatic restart")
            // Wait for the pause result.
            .await?,
        // Finish the pause result print call.
    );
    // Print the resume child result.
    print_result(
        // Label the resume result.
        "resume_child",
        // Send the resume child command.
        handle
            // Resume lifecycle governance.
            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
            // Wait for the resume result.
            .await?,
        // Finish the resume result print call.
    );
    // Print the quarantine child result.
    print_result(
        // Label the quarantine result.
        "quarantine_child",
        // Send the quarantine child command.
        handle
            // Quarantine the child for manual investigation.
            .quarantine_child(child_id, "operator", "manual investigation")
            // Wait for the quarantine result.
            .await?,
        // Finish the quarantine result print call.
    );
    // Print the current state result.
    print_result("current_state", handle.current_state().await?);

    // Drain already available runtime events.
    while let Ok(event) = events.try_recv() {
        // Print one runtime event.
        println!("event={event}");
        // Finish the event drain loop.
    }

    // Print the shutdown result.
    print_result(
        // Label the shutdown result.
        "shutdown_tree",
        // Send the shutdown command.
        handle
            // Request tree shutdown.
            .shutdown_tree("operator", "runtime control story complete")
            // Wait for the shutdown result.
            .await?,
        // Finish the shutdown result print call.
    );

    // Finish the example successfully.
    Ok(())
    // End the runtime control example.
}

pub async fn start_from_config_state( state: ConfigState, ) -> Result<SupervisorHandle, SupervisorError>

Starts a supervisor runtime from validated configuration state.

Arguments

• state: Validated configuration state owned by the caller.

Returns

Returns a SupervisorHandle only after configuration has produced a valid supervisor specification.

Examples found in repository

examples/demo/runner.rs (line 39)

pub(crate) async fn run_demo(
    // Continue the demo expression.
    config_path: PathBuf,
    // Continue the demo expression.
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Load the full demo configuration.
    let state = load_config_state(&config_path)?;
    // Start the demo-owned dashboard IPC and registration runtime.
    let demo_runtime = start_demo_dashboard_runtime(&state)?;
    // Build a pure supervisor runtime configuration.
    let supervisor_state = supervisor_runtime_state(state);
    // Start the library supervisor without core demo state intrusion.
    let handle = Supervisor::start_from_config_state(supervisor_state).await?;
    // Query current state once to prove the runtime is live.
    let current = handle.current_state().await?;
    // Print the runtime state for operator inspection.
    println!("{current:#?}");
    // Print the demo startup summary.
    print_startup_summary(&config_path, demo_runtime.as_ref());
    // Wait until the operator stops the demo process.
    tokio::signal::ctrl_c().await?;
    // Shut down the supervisor tree before dropping resources.
    shutdown_demo(&handle).await?;
    // Drop the supervisor handle explicitly.
    drop(handle);
    // Drop the demo runtime explicitly so the IPC socket is cleaned up.
    drop(demo_runtime);
    // Finish the demo successfully.
    Ok(())
    // End demo runner.
}

pub async fn start_from_config_file( path: impl AsRef<Path>, ) -> Result<SupervisorHandle, SupervisorError>

Starts a supervisor runtime from a YAML configuration file.

Arguments

• path: Path to the YAML configuration file.

Returns

Returns a SupervisorHandle only after the configuration file has loaded and validated successfully.

pub async fn start_with_policy( spec: SupervisorSpec, shutdown_policy: ShutdownPolicy, ) -> Result<SupervisorHandle, SupervisorError>

Starts a supervisor runtime with an explicit shutdown policy.

Arguments

• spec: Supervisor specification owned by the caller.
• shutdown_policy: Policy used by the control loop.

Returns

Returns a SupervisorHandle connected to the runtime control loop.

Trait Implementations

impl Clone for Supervisor

fn clone(&self) -> Supervisor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Supervisor

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

Formats the value using the given formatter.

impl Default for Supervisor

fn default() -> Supervisor

Returns the “default value” for a type.

impl Copy for Supervisor