Skip to main content

SupervisorHandle

rust_supervisor::control::handle

Struct SupervisorHandle 

Source 
pub struct SupervisorHandle { /* private fields */ }
Expand description

Cloneable handle used to control a running supervisor.

Implementations§

Source§

impl SupervisorHandle

Source

pub fn new( command_sender: Sender<RuntimeCommand>, event_sender: Sender<String>, ) -> Self

Creates a runtime handle from channel senders.

§Arguments
  • command_sender: Sender used to submit runtime commands.
  • event_sender: Sender used to subscribe to lifecycle events.
§Returns

Returns a SupervisorHandle.

Source

pub async fn add_child( &self, target: SupervisorPath, child_manifest: impl Into<String>, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Adds a child manifest under a supervisor path.

§Arguments
  • target: Supervisor path that should receive the child.
  • child_manifest: Child manifest text supplied by the caller.
  • requested_by: Actor that requested the command.
  • reason: Human-readable command reason.
§Returns

Returns a CommandResult after the runtime accepts the command.

Examples found in repository?
examples/runtime_control_story.rs (lines 34-44)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}
Source

pub async fn remove_child( &self, child_id: ChildId, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Removes a child from runtime governance.

§Arguments
  • child_id: Target child identifier.
  • requested_by: Actor that requested the command.
  • reason: Human-readable command reason.
§Returns

Returns a CommandResult after removal or idempotent reuse.

Source

pub async fn restart_child( &self, child_id: ChildId, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Restarts a child explicitly.

§Arguments
  • child_id: Target child identifier.
  • requested_by: Actor that requested the command.
  • reason: Human-readable command reason.
§Returns

Returns a CommandResult after restart dispatch.

Source

pub async fn pause_child( &self, child_id: ChildId, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Pauses a child idempotently.

§Arguments
  • child_id: Target child identifier.
  • requested_by: Actor that requested the command.
  • reason: Human-readable command reason.
§Returns

Returns the current child state after the command.

Examples found in repository?
examples/runtime_control_story.rs (line 57)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}
Source

pub async fn resume_child( &self, child_id: ChildId, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Resumes a child idempotently.

§Arguments
  • child_id: Target child identifier.
  • requested_by: Actor that requested the command.
  • reason: Human-readable command reason.
§Returns

Returns the current child state after the command.

Examples found in repository?
examples/runtime_control_story.rs (line 69)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}
Source

pub async fn quarantine_child( &self, child_id: ChildId, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Quarantines a child idempotently.

§Arguments
  • child_id: Target child identifier.
  • requested_by: Actor that requested the command.
  • reason: Human-readable command reason.
§Returns

Returns the current child state after the command.

Examples found in repository?
examples/runtime_control_story.rs (line 81)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}
Source

pub async fn shutdown_tree( &self, requested_by: impl Into<String>, reason: impl Into<String>, ) -> Result<CommandResult, SupervisorError>

Shuts down the supervisor tree idempotently.

§Arguments
  • requested_by: Actor that requested shutdown.
  • reason: Human-readable shutdown reason.
§Returns

Returns the current shutdown result.

Examples found in repository?
examples/demo/shutdown.rs (line 21)
15pub(crate) async fn shutdown_demo(
16    // Continue the demo expression.
17    handle: &SupervisorHandle,
18    // Continue the demo expression.
19) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
20    // Send a visible shutdown reason through the public handle.
21    handle.shutdown_tree("operator", "demo shutdown").await?;
22    // Finish graceful shutdown.
23    Ok(())
24    // End shutdown helper.
25}
More examples
Hide additional examples
examples/supervisor_quickstart.rs (line 29)
15async fn main() -> ExampleResult {
16    // Load centralized YAML configuration.
17    let state = load_config_state("examples/config/supervisor.yaml")?;
18    // Derive the supervisor specification from configuration.
19    let spec = state.to_supervisor_spec()?;
20    // Start the supervisor runtime from the specification.
21    let handle = Supervisor::start(spec).await?;
22    // Query the current runtime state.
23    let current = handle.current_state().await?;
24    // Print the current state for the learner.
25    println!("{current:#?}");
26    // Use the runtime handle for the shutdown request.
27    handle
28        // Request tree shutdown with audit metadata.
29        .shutdown_tree("operator", "quickstart complete")
30        // Wait for the shutdown command result.
31        .await?;
32    // Finish the example successfully.
33    Ok(())
34    // End the quickstart example.
35}
examples/observability_probe.rs (line 39)
15async fn main() -> ExampleResult {
16    // Load centralized YAML configuration.
17    let state = load_config_state("examples/config/supervisor.yaml")?;
18    // Derive the supervisor specification from configuration.
19    let spec = state.to_supervisor_spec()?;
20    // Start the supervisor runtime from the specification.
21    let handle = Supervisor::start(spec).await?;
22    // Subscribe to runtime event text.
23    let mut events = handle.subscribe_events();
24    // Query the current runtime state.
25    let current = handle.current_state().await?;
26    // Print the current state for the learner.
27    println!("current={current:#?}");
28    // Read one emitted runtime event when it is available.
29    let received = events.recv().await;
30    // Continue only when an event was received.
31    if let Ok(event) = received {
32        // Print the observed runtime event.
33        println!("event={event:#?}");
34        // Finish the optional event display.
35    }
36    // Use the runtime handle for the shutdown request.
37    handle
38        // Request tree shutdown with audit metadata.
39        .shutdown_tree("operator", "observability probe complete")
40        // Wait for the shutdown command result.
41        .await?;
42    // Finish the example successfully.
43    Ok(())
44    // End the observability example.
45}
examples/shutdown_tree.rs (line 45)
17async fn main() -> ExampleResult {
18    // Load centralized YAML configuration.
19    let state = load_config_state("examples/config/supervisor.yaml")?;
20    // Derive the supervisor specification from configuration.
21    let spec = state.to_supervisor_spec()?;
22    // Start the supervisor runtime from the specification.
23    let handle = Supervisor::start(spec).await?;
24    // Build the visible shutdown phase list.
25    let phases = [
26        // Show the stop request phase.
27        ShutdownPhase::RequestStop,
28        // Show the graceful drain phase.
29        ShutdownPhase::GracefulDrain,
30        // Show the abort stragglers phase.
31        ShutdownPhase::AbortStragglers,
32        // Show the final reconcile phase.
33        ShutdownPhase::Reconcile,
34        // Finish the shutdown phase list.
35    ];
36    // Iterate over the visible shutdown phases.
37    for phase in phases {
38        // Print each planned phase.
39        println!("planned phase={phase:#?}");
40        // Finish the phase display loop.
41    }
42    // Use the runtime handle for the shutdown request.
43    handle
44        // Request tree shutdown with audit metadata.
45        .shutdown_tree("operator", "shutdown tree example")
46        // Wait for the shutdown command result.
47        .await?;
48    // Finish the example successfully.
49    Ok(())
50    // End the shutdown example.
51}
examples/runtime_control_story.rs (line 103)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}
Source

pub async fn current_state(&self) -> Result<CommandResult, SupervisorError>

Queries the current runtime state.

§Arguments

This function has no arguments.

§Returns

Returns a CommandResult::CurrentState value.

Examples found in repository?
examples/supervisor_quickstart.rs (line 23)
15async fn main() -> ExampleResult {
16    // Load centralized YAML configuration.
17    let state = load_config_state("examples/config/supervisor.yaml")?;
18    // Derive the supervisor specification from configuration.
19    let spec = state.to_supervisor_spec()?;
20    // Start the supervisor runtime from the specification.
21    let handle = Supervisor::start(spec).await?;
22    // Query the current runtime state.
23    let current = handle.current_state().await?;
24    // Print the current state for the learner.
25    println!("{current:#?}");
26    // Use the runtime handle for the shutdown request.
27    handle
28        // Request tree shutdown with audit metadata.
29        .shutdown_tree("operator", "quickstart complete")
30        // Wait for the shutdown command result.
31        .await?;
32    // Finish the example successfully.
33    Ok(())
34    // End the quickstart example.
35}
More examples
Hide additional examples
examples/observability_probe.rs (line 25)
15async fn main() -> ExampleResult {
16    // Load centralized YAML configuration.
17    let state = load_config_state("examples/config/supervisor.yaml")?;
18    // Derive the supervisor specification from configuration.
19    let spec = state.to_supervisor_spec()?;
20    // Start the supervisor runtime from the specification.
21    let handle = Supervisor::start(spec).await?;
22    // Subscribe to runtime event text.
23    let mut events = handle.subscribe_events();
24    // Query the current runtime state.
25    let current = handle.current_state().await?;
26    // Print the current state for the learner.
27    println!("current={current:#?}");
28    // Read one emitted runtime event when it is available.
29    let received = events.recv().await;
30    // Continue only when an event was received.
31    if let Ok(event) = received {
32        // Print the observed runtime event.
33        println!("event={event:#?}");
34        // Finish the optional event display.
35    }
36    // Use the runtime handle for the shutdown request.
37    handle
38        // Request tree shutdown with audit metadata.
39        .shutdown_tree("operator", "observability probe complete")
40        // Wait for the shutdown command result.
41        .await?;
42    // Finish the example successfully.
43    Ok(())
44    // End the observability example.
45}
examples/demo/runner.rs (line 41)
27pub(crate) async fn run_demo(
28    // Continue the demo expression.
29    config_path: PathBuf,
30    // Continue the demo expression.
31) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
32    // Load the full demo configuration.
33    let state = load_config_state(&config_path)?;
34    // Start the demo-owned dashboard IPC and registration runtime.
35    let demo_runtime = start_demo_dashboard_runtime(&state)?;
36    // Build a pure supervisor runtime configuration.
37    let supervisor_state = supervisor_runtime_state(state);
38    // Start the library supervisor without core demo state intrusion.
39    let handle = Supervisor::start_from_config_state(supervisor_state).await?;
40    // Query current state once to prove the runtime is live.
41    let current = handle.current_state().await?;
42    // Print the runtime state for operator inspection.
43    println!("{current:#?}");
44    // Print the demo startup summary.
45    print_startup_summary(&config_path, demo_runtime.as_ref());
46    // Wait until the operator stops the demo process.
47    tokio::signal::ctrl_c().await?;
48    // Shut down the supervisor tree before dropping resources.
49    shutdown_demo(&handle).await?;
50    // Drop the supervisor handle explicitly.
51    drop(handle);
52    // Drop the demo runtime explicitly so the IPC socket is cleaned up.
53    drop(demo_runtime);
54    // Finish the demo successfully.
55    Ok(())
56    // End demo runner.
57}
examples/runtime_control_story.rs (line 87)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}
Source

pub fn subscribe_events(&self) -> Receiver<String>

Subscribes to runtime event text emitted by the control loop.

§Arguments

This function has no arguments.

§Returns

Returns a broadcast receiver for event text.

Examples found in repository?
examples/observability_probe.rs (line 23)
15async fn main() -> ExampleResult {
16    // Load centralized YAML configuration.
17    let state = load_config_state("examples/config/supervisor.yaml")?;
18    // Derive the supervisor specification from configuration.
19    let spec = state.to_supervisor_spec()?;
20    // Start the supervisor runtime from the specification.
21    let handle = Supervisor::start(spec).await?;
22    // Subscribe to runtime event text.
23    let mut events = handle.subscribe_events();
24    // Query the current runtime state.
25    let current = handle.current_state().await?;
26    // Print the current state for the learner.
27    println!("current={current:#?}");
28    // Read one emitted runtime event when it is available.
29    let received = events.recv().await;
30    // Continue only when an event was received.
31    if let Ok(event) = received {
32        // Print the observed runtime event.
33        println!("event={event:#?}");
34        // Finish the optional event display.
35    }
36    // Use the runtime handle for the shutdown request.
37    handle
38        // Request tree shutdown with audit metadata.
39        .shutdown_tree("operator", "observability probe complete")
40        // Wait for the shutdown command result.
41        .await?;
42    // Finish the example successfully.
43    Ok(())
44    // End the observability example.
45}
More examples
Hide additional examples
examples/runtime_control_story.rs (line 27)
19async fn main() -> ExampleResult {
20    // Load centralized YAML configuration.
21    let state = load_config_state("examples/config/supervisor.yaml")?;
22    // Derive the supervisor specification from configuration.
23    let spec = state.to_supervisor_spec()?;
24    // Start the supervisor runtime from the specification.
25    let handle = Supervisor::start(spec).await?;
26    // Subscribe to runtime event text.
27    let mut events = handle.subscribe_events();
28    // Build the child identifier used by operator commands.
29    let child_id = ChildId::new("market_feed");
30
31    // Send an add child command through the control handle.
32    let add = handle
33        // Add a manifest under the root supervisor.
34        .add_child(
35            // Target the root supervisor.
36            SupervisorPath::root(),
37            // Provide the child manifest text.
38            "id=market_feed kind=AsyncWorker readiness=Explicit",
39            // Provide the requesting actor.
40            "operator",
41            // Provide the audit reason.
42            "attach market feed during incident rehearsal",
43            // Finish the add child arguments.
44        )
45        // Wait for the add child command result.
46        .await?;
47    // Print the add child result.
48    print_result("add_child", add);
49
50    // Print the pause child result.
51    print_result(
52        // Label the pause result.
53        "pause_child",
54        // Send the pause child command.
55        handle
56            // Pause automatic governance.
57            .pause_child(child_id.clone(), "operator", "stop automatic restart")
58            // Wait for the pause result.
59            .await?,
60        // Finish the pause result print call.
61    );
62    // Print the resume child result.
63    print_result(
64        // Label the resume result.
65        "resume_child",
66        // Send the resume child command.
67        handle
68            // Resume lifecycle governance.
69            .resume_child(child_id.clone(), "operator", "resume lifecycle governance")
70            // Wait for the resume result.
71            .await?,
72        // Finish the resume result print call.
73    );
74    // Print the quarantine child result.
75    print_result(
76        // Label the quarantine result.
77        "quarantine_child",
78        // Send the quarantine child command.
79        handle
80            // Quarantine the child for manual investigation.
81            .quarantine_child(child_id, "operator", "manual investigation")
82            // Wait for the quarantine result.
83            .await?,
84        // Finish the quarantine result print call.
85    );
86    // Print the current state result.
87    print_result("current_state", handle.current_state().await?);
88
89    // Drain already available runtime events.
90    while let Ok(event) = events.try_recv() {
91        // Print one runtime event.
92        println!("event={event}");
93        // Finish the event drain loop.
94    }
95
96    // Print the shutdown result.
97    print_result(
98        // Label the shutdown result.
99        "shutdown_tree",
100        // Send the shutdown command.
101        handle
102            // Request tree shutdown.
103            .shutdown_tree("operator", "runtime control story complete")
104            // Wait for the shutdown result.
105            .await?,
106        // Finish the shutdown result print call.
107    );
108
109    // Finish the example successfully.
110    Ok(())
111    // End the runtime control example.
112}

Trait Implementations§

Source§

impl Clone for SupervisorHandle

Source§

fn clone(&self) -> SupervisorHandle

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for SupervisorHandle

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DynClone for T
where T: Clone,

Source§

fn __clone_box(&self, _: Private) -> *mut ()

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Paint for T
where T: ?Sized,

Source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
Source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Primary].

§Example
println!("{}", value.primary());
Source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Fixed].

§Example
println!("{}", value.fixed(color));
Source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Rgb].

§Example
println!("{}", value.rgb(r, g, b));
Source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Black].

§Example
println!("{}", value.black());
Source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Red].

§Example
println!("{}", value.red());
Source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Green].

§Example
println!("{}", value.green());
Source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Yellow].

§Example
println!("{}", value.yellow());
Source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Blue].

§Example
println!("{}", value.blue());
Source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Magenta].

§Example
println!("{}", value.magenta());
Source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Cyan].

§Example
println!("{}", value.cyan());
Source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: White].

§Example
println!("{}", value.white());
Source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlack].

§Example
println!("{}", value.bright_black());
Source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightRed].

§Example
println!("{}", value.bright_red());
Source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightGreen].

§Example
println!("{}", value.bright_green());
Source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightYellow].

§Example
println!("{}", value.bright_yellow());
Source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlue].

§Example
println!("{}", value.bright_blue());
Source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.bright_magenta());
Source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightCyan].

§Example
println!("{}", value.bright_cyan());
Source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightWhite].

§Example
println!("{}", value.bright_white());
Source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
Source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Primary].

§Example
println!("{}", value.on_primary());
Source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Fixed].

§Example
println!("{}", value.on_fixed(color));
Source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Rgb].

§Example
println!("{}", value.on_rgb(r, g, b));
Source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Black].

§Example
println!("{}", value.on_black());
Source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Red].

§Example
println!("{}", value.on_red());
Source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Green].

§Example
println!("{}", value.on_green());
Source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Yellow].

§Example
println!("{}", value.on_yellow());
Source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Blue].

§Example
println!("{}", value.on_blue());
Source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Magenta].

§Example
println!("{}", value.on_magenta());
Source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Cyan].

§Example
println!("{}", value.on_cyan());
Source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: White].

§Example
println!("{}", value.on_white());
Source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlack].

§Example
println!("{}", value.on_bright_black());
Source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightRed].

§Example
println!("{}", value.on_bright_red());
Source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightGreen].

§Example
println!("{}", value.on_bright_green());
Source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightYellow].

§Example
println!("{}", value.on_bright_yellow());
Source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlue].

§Example
println!("{}", value.on_bright_blue());
Source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.on_bright_magenta());
Source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightCyan].

§Example
println!("{}", value.on_bright_cyan());
Source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightWhite].

§Example
println!("{}", value.on_bright_white());
Source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
Source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Bold].

§Example
println!("{}", value.bold());
Source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Dim].

§Example
println!("{}", value.dim());
Source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Italic].

§Example
println!("{}", value.italic());
Source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Underline].

§Example
println!("{}", value.underline());

Returns self with the attr() set to [Attribute :: Blink].

§Example
println!("{}", value.blink());

Returns self with the attr() set to [Attribute :: RapidBlink].

§Example
println!("{}", value.rapid_blink());
Source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Invert].

§Example
println!("{}", value.invert());
Source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Conceal].

§Example
println!("{}", value.conceal());
Source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Strike].

§Example
println!("{}", value.strike());
Source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
Source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Mask].

§Example
println!("{}", value.mask());
Source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Wrap].

§Example
println!("{}", value.wrap());
Source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Linger].

§Example
println!("{}", value.linger());
Source§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1:

renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to [Quirk :: Clear].

§Example
println!("{}", value.clear());
Source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Resetting].

§Example
println!("{}", value.resetting());
Source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Bright].

§Example
println!("{}", value.bright());
Source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: OnBright].

§Example
println!("{}", value.on_bright());
Source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
Source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
Source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more