pub struct TaskRuntime { /* private fields */ }Expand description
The core runtime for managing supervised tasks.
TaskRuntime is responsible for:
- Registering tasks and their configurations.
- Managing task lifecycle (start, stop, pause, resume, restart).
- Handling global and per-task concurrency limits.
- Orchestrating task dependencies and prerequisites.
- Distributing supervisor events to registered listeners.
- Persisting and restoring task states.
It is typically created by the crate::Supervisor builder and then
used to interact with the running supervised system.
Implementations§
Source§impl TaskRuntime
impl TaskRuntime
Sourcepub fn with_global_concurrency_limit(&mut self, limit: usize) -> &mut Self
pub fn with_global_concurrency_limit(&mut self, limit: usize) -> &mut Self
Sets a global concurrency limit for the supervisor.
This limit applies to all tasks and restricts how many can be actively
running their run() method at any given time.
Sourcepub fn with_event_channel_capacity(&mut self, capacity: usize) -> &mut Self
pub fn with_event_channel_capacity(&mut self, capacity: usize) -> &mut Self
Sets the event broadcast channel capacity.
The default is 1024. Increase this if you have many tasks emitting
events rapidly and observe EventsDropped warnings.
Sourcepub fn register<T: SupervisedTask + 'static>(&mut self, task: T) -> &mut Self
pub fn register<T: SupervisedTask + 'static>(&mut self, task: T) -> &mut Self
Registers a task for supervision.
This method adds the task to the runtime’s internal registry but does not
start its execution. Tasks are started when start_all() is called.
Sourcepub fn register_many<T: SupervisedTask + 'static>(
&mut self,
tasks: Vec<T>,
) -> &mut Self
pub fn register_many<T: SupervisedTask + 'static>( &mut self, tasks: Vec<T>, ) -> &mut Self
Registers multiple tasks of the same type at once.
Sourcepub fn register_boxed(&mut self, task: Box<dyn SupervisedTask>) -> &mut Self
pub fn register_boxed(&mut self, task: Box<dyn SupervisedTask>) -> &mut Self
Registers a task from a boxed trait object.
Useful when managing a heterogeneous collection of tasks.
Sourcepub fn register_arc(&mut self, task: Arc<dyn SupervisedTask>) -> &mut Self
pub fn register_arc(&mut self, task: Arc<dyn SupervisedTask>) -> &mut Self
Registers a task from an Arc (zero extra allocation).
This is the most efficient way to add a task if you already have an Arc handle.
Sourcepub fn add_task<T: SupervisedTask + 'static>(
&mut self,
task: T,
) -> Result<(), SupervisorError>
pub fn add_task<T: SupervisedTask + 'static>( &mut self, task: T, ) -> Result<(), SupervisorError>
Registers and starts a new task at runtime.
This allows adding tasks to an already running supervisor.
§Errors
Returns SupervisorError::ConfigurationError if a task with the same ID already exists.
Returns SupervisorError::DependencyValidation if a declared dependency is unknown.
Sourcepub fn restart_task(&self, id: &str) -> Result<(), SupervisorError>
pub fn restart_task(&self, id: &str) -> Result<(), SupervisorError>
Manually restarts a task by its ID.
This sends a Restart control message to the task’s supervision loop.
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub fn pause_task(&self, id: &str) -> Result<(), SupervisorError>
pub fn pause_task(&self, id: &str) -> Result<(), SupervisorError>
Pauses a task by its ID.
This sends a Pause control message to the task’s supervision loop.
A paused task will temporarily stop executing its run() method.
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub fn resume_task(&self, id: &str) -> Result<(), SupervisorError>
pub fn resume_task(&self, id: &str) -> Result<(), SupervisorError>
Resumes a paused task by its ID.
This sends a Resume control message to the task’s supervision loop,
allowing it to continue execution.
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub fn reset_circuit_breaker(&self, id: &str) -> Result<(), SupervisorError>
pub fn reset_circuit_breaker(&self, id: &str) -> Result<(), SupervisorError>
Resets the circuit breaker for a task by its ID.
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub async fn update_restart_policy(
&self,
id: &str,
new_policy: RestartPolicy,
) -> Result<(), SupervisorError>
pub async fn update_restart_policy( &self, id: &str, new_policy: RestartPolicy, ) -> Result<(), SupervisorError>
Updates the restart policy for a task at runtime.
The new policy will take effect on the next restart attempt. This does not trigger an immediate restart.
§Arguments
id- The task ID to updatenew_policy- The new restart policy to apply
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub async fn update_backoff_strategy(
&self,
id: &str,
new_strategy: BackoffStrategy,
) -> Result<(), SupervisorError>
pub async fn update_backoff_strategy( &self, id: &str, new_strategy: BackoffStrategy, ) -> Result<(), SupervisorError>
Updates the backoff strategy for a task at runtime.
The new strategy will take effect on the next restart attempt. This does not trigger an immediate restart.
§Arguments
id- The task ID to updatenew_strategy- The new backoff strategy to apply
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub async fn set_task_enabled(
&self,
id: &str,
enabled: bool,
) -> Result<(), SupervisorError>
pub async fn set_task_enabled( &self, id: &str, enabled: bool, ) -> Result<(), SupervisorError>
Enables or disables a task at runtime.
A disabled task will not restart after failure but will continue running
if already executing. To stop a running task, use stop_task() first.
§Arguments
id- The task ID to enable/disableenabled- Whether the task should be enabled
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub async fn get_task_config(&self, id: &str) -> Option<TaskConfig>
pub async fn get_task_config(&self, id: &str) -> Option<TaskConfig>
Sourcepub async fn is_task_enabled(&self, id: &str) -> bool
pub async fn is_task_enabled(&self, id: &str) -> bool
Sourcepub fn start_group(&mut self, group_id: &str) -> usize
pub fn start_group(&mut self, group_id: &str) -> usize
Sourcepub async fn stop_group(&mut self, group_id: &str) -> usize
pub async fn stop_group(&mut self, group_id: &str) -> usize
Sourcepub fn restart_group(&self, group_id: &str) -> usize
pub fn restart_group(&self, group_id: &str) -> usize
Sourcepub fn list_group_tasks(&self, group_id: &str) -> Vec<String>
pub fn list_group_tasks(&self, group_id: &str) -> Vec<String>
Sourcepub async fn get_group_health(&self, group_id: &str) -> HealthStatus
pub async fn get_group_health(&self, group_id: &str) -> HealthStatus
Gets the aggregated health status for a task group.
The group health is determined by the worst health status among all tasks in the group:
- If any task is Unhealthy, the group is Unhealthy
- Else if any task is Degraded, the group is Degraded
- Else if all tasks are Healthy, the group is Healthy
- If no tasks are in the group, returns Unknown
§Arguments
group_id- The group identifier to query
§Returns
Aggregated HealthStatus for the group
Sourcepub async fn get_group_health_details(&self, group_id: &str) -> Vec<TaskSummary>
pub async fn get_group_health_details(&self, group_id: &str) -> Vec<TaskSummary>
Sourcepub async fn remove_task(
&mut self,
id: &str,
) -> Result<Option<SupervisionResult>, SupervisorError>
pub async fn remove_task( &mut self, id: &str, ) -> Result<Option<SupervisionResult>, SupervisorError>
Stops and removes a task by its ID.
This sends a Stop control message to the task, waits for it to terminate,
and then removes it from the runtime.
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Returns SupervisorError::TaskPanicked if the task panicked during removal.
Sourcepub async fn get_task_info(
&self,
id: &str,
) -> Result<TaskSummary, SupervisorError>
pub async fn get_task_info( &self, id: &str, ) -> Result<TaskSummary, SupervisorError>
Retrieves detailed information about a specific task.
This includes its ID, name, and current health status.
§Errors
Returns SupervisorError::UnknownTask if no task with the given ID is found.
Sourcepub async fn list_tasks(&self) -> Vec<TaskSummary>
pub async fn list_tasks(&self) -> Vec<TaskSummary>
Lists summaries of all currently registered tasks.
Sourcepub fn with_state_store(&mut self, store: Arc<dyn TaskStateStore>) -> &mut Self
pub fn with_state_store(&mut self, store: Arc<dyn TaskStateStore>) -> &mut Self
Sets a custom state store for persisting task states.
This method is typically used by the crate::Supervisor builder.
Sourcepub fn subscribe(&self) -> Receiver<SupervisorEvent>
pub fn subscribe(&self) -> Receiver<SupervisorEvent>
Subscribes to the supervisor’s event stream.
Returns a tokio::sync::broadcast::Receiver that will receive all
SupervisorEvents emitted by the runtime.
Sourcepub fn add_listener(
&mut self,
listener: Arc<dyn SupervisorEventListener>,
) -> &mut Self
pub fn add_listener( &mut self, listener: Arc<dyn SupervisorEventListener>, ) -> &mut Self
Registers an event listener.
This method is typically used by the crate::Supervisor builder.
Sourcepub fn add_prerequisite(
&mut self,
name: &'static str,
fut: PrerequisiteFuture,
) -> &mut Self
pub fn add_prerequisite( &mut self, name: &'static str, fut: PrerequisiteFuture, ) -> &mut Self
Adds an asynchronous prerequisite gate that must resolve before any task starts.
This method is typically used by the crate::Supervisor builder.
Sourcepub fn add_prerequisite_fn<F, Fut>(
&mut self,
name: &'static str,
f: F,
) -> &mut Self
pub fn add_prerequisite_fn<F, Fut>( &mut self, name: &'static str, f: F, ) -> &mut Self
Adds an asynchronous prerequisite gate using a closure.
This method is typically used by the crate::Supervisor builder.
Sourcepub async fn start_all(&mut self) -> Result<(), SupervisorError>
pub async fn start_all(&mut self) -> Result<(), SupervisorError>
Starts all registered tasks.
This method first runs all prerequisites, then validates dependencies, and finally spawns the supervision loop for each task.
§Errors
Returns SupervisorError if any prerequisite fails or if the dependency graph is invalid.
Sourcepub fn start_one<T: SupervisedTask + 'static>(
task: T,
) -> JoinHandle<SupervisionResult> ⓘ
pub fn start_one<T: SupervisedTask + 'static>( task: T, ) -> JoinHandle<SupervisionResult> ⓘ
Starts a single task with no dependencies (fire and forget).
This is a convenience function for simple, isolated task supervision
without needing a full TaskRuntime setup.
Sourcepub async fn wait_any(&mut self) -> SupervisionResult
pub async fn wait_any(&mut self) -> SupervisionResult
Waits for any one supervised task to terminate.
Returns the SupervisionResult of the first task that finishes.
Sourcepub async fn wait_all(&mut self) -> Vec<SupervisionResult>
pub async fn wait_all(&mut self) -> Vec<SupervisionResult>
Waits for all supervised tasks to terminate.
Returns a vector of SupervisionResult for all tasks.
Sourcepub async fn shutdown(self)
pub async fn shutdown(self)
Initiates a graceful shutdown of all supervised tasks.
This sends a Stop control message to each task and waits for them
to complete their on_shutdown() hooks and terminate.
Shutdown is performed in reverse dependency order (leaves first, then roots).
Sourcepub fn task_count(&self) -> usize
pub fn task_count(&self) -> usize
Returns the number of tasks currently being supervised.