Struct SupervisorHandle

pub struct SupervisorHandle { /* private fields */ }

Handle used to interact with the Supervisor.

Implementations

impl SupervisorHandle

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

Waits for the supervisor to complete its execution.

Returns

• Ok(()) if the supervisor completed successfully.
• Err(SupervisorError) if the supervisor returned an error.

Examples found in repository

examples/simple.rs (line 88)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

pub fn add_task<T: CloneableSupervisedTask + 'static>( &self, task_name: &str, task: T, ) -> Result<(), SupervisorHandleError>

Adds a new task to the supervisor.

This method sends a message to the supervisor to add a new task with the specified name.

Arguments

• task_name: The unique name of the task.
• task: The task to be added, which must implement SupervisedTask.

Returns

• Ok(()) if the message was sent successfully.
• Err(SendError) if the supervisor is no longer running.

Examples found in repository

examples/simple.rs (line 40)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

pub fn restart(&self, task_name: &str) -> Result<(), SupervisorHandleError>

Requests the supervisor to restart a specific task.

This method sends a message to the supervisor to restart the task with the given name.

Arguments

• task_name: The name of the task to restart.

Returns

• Ok(()) if the message was sent successfully.
• Err(SendError) if the supervisor is no longer running.

Examples found in repository

examples/simple.rs (line 54)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

pub fn kill_task(&self, task_name: &str) -> Result<(), SupervisorHandleError>

Requests the supervisor to kill a specific task.

This method sends a message to the supervisor to terminate the task with the given name.

Arguments

• task_name: The name of the task to kill.

Returns

• Ok(()) if the message was sent successfully.
• Err(SendError) if the supervisor is no longer running.

Examples found in repository

examples/simple.rs (line 71)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

pub fn shutdown(&self) -> Result<(), SupervisorHandleError>

Requests the supervisor to shut down all tasks and stop supervision.

This method sends a message to the supervisor to terminate all tasks and cease operation.

Returns

• Ok(()) if the message was sent successfully.
• Err(SendError) if the supervisor is no longer running.

Examples found in repository

examples/simple.rs (line 84)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

pub async fn get_task_status( &self, task_name: &str, ) -> Result<Option<TaskStatus>, SupervisorHandleError>

Queries the status of a specific task asynchronously.

This method sends a request to the supervisor to retrieve the status of the specified task and awaits the response.

Arguments

• task_name: The name of the task to query.

Returns

• Ok(Some(TaskStatus)) if the task exists and its status is returned.
• Ok(None) if the task does not exist.
• Err(RecvError) if communication with the supervisor fails (e.g., it has shut down).

Examples found in repository

examples/simple.rs (line 45)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

pub async fn get_all_task_statuses( &self, ) -> Result<HashMap<String, TaskStatus>, SupervisorHandleError>

Queries the statuses of all tasks asynchronously.

This method sends a request to the supervisor to retrieve the statuses of all tasks and awaits the response.

Returns

• Ok(HashMap<TaskName, TaskStatus>) containing the statuses of all tasks.
• Err(RecvError) if communication with the supervisor fails (e.g., it has shut down).

Examples found in repository

examples/simple.rs (line 58)

async fn main() -> Result<(), Box<dyn Error>> {
    // Build the supervisor with no initial tasks
    let supervisor = SupervisorBuilder::default().build();

    // Run the supervisor and get the handle
    let handle = supervisor.run();

    // Clone the handle for use in a separate task
    let h = handle.clone();

    // Spawn a task to manage and monitor the supervisor
    tokio::spawn(async move {
        // Add a new task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Adding a task after 5 seconds...");
        h.add_task("task1", MyTask { emoji: '🆕' })
            .expect("Failed to add task");

        // Check the status of the task after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status: {status:?}"),
            Ok(None) => println!("Task 'task1' not found"),
            Err(e) => println!("Error getting task status: {e}"),
        }

        // Restart the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Restarting task after 5 seconds...");
        h.restart("task1").expect("Failed to restart task");

        // Check all task statuses after 2 seconds
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_all_task_statuses().await {
            Ok(statuses) => {
                println!("All task statuses:");
                for (name, status) in statuses {
                    println!("  {name}: {status:?}");
                }
            }
            Err(e) => println!("Error getting all task statuses: {}", e),
        }

        // Kill the task after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Killing task after 5 seconds...");
        h.kill_task("task1").expect("Failed to kill task");

        // Check the status again after killing
        tokio::time::sleep(Duration::from_secs(2)).await;
        match h.get_task_status("task1").await {
            Ok(Some(status)) => println!("Task 'task1' status after kill: {:?}", status),
            Ok(None) => println!("Task 'task1' not found after kill"),
            Err(e) => println!("Error getting task status after kill: {}", e),
        }

        // Shutdown the supervisor after 5 seconds
        tokio::time::sleep(Duration::from_secs(5)).await;
        println!("Shutting down supervisor...");
        h.shutdown().expect("Failed to shutdown supervisor");
    });

    // Wait for the supervisor to complete
    handle.wait().await?;
    println!("All tasks died and supervisor shut down! 🫡");

    Ok(())
}

Trait Implementations

impl Clone for SupervisorHandle

fn clone(&self) -> SupervisorHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SupervisorHandle

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

Formats the value using the given formatter.

impl Drop for SupervisorHandle

fn drop(&mut self)

Automatically shuts down the supervisor when the handle is dropped.