task_supervisor/
lib.rs

1//! # task-supervisor
2//!
3//! [![Crates.io](https://img.shields.io/crates/v/supervisor.svg)](https://crates.io/crates/task-supervisor)
4//! [![Docs.rs](https://docs.rs/supervisor/badge.svg)](https://docs.rs/task-supervisor)
5//!
6//! `task-supervisor` helps you keep Tokio tasks alive.
7//! It watches each task, restarts it if it crashes or stops responding, and lets you add, restart, or kill tasks at runtime.
8//!
9//! ## Install
10//!
11//! ```bash
12//! cargo add task-supervisor
13//! ```
14//!
15//! ## Quick example
16//!
17//! ```rust,no_run
18//! use task_supervisor::{SupervisorBuilder, SupervisedTask, TaskResult};
19//!
20//! #[derive(Clone)]
21//! struct Printer;
22//!
23//! impl SupervisedTask for Printer {
24//!     async fn run(&mut self) -> TaskResult {
25//!         println!("hello");
26//!         Ok(())
27//!     }
28//! }
29//!
30//! #[tokio::main]
31//! async fn main() {
32//!     let supervisor = SupervisorBuilder::default()
33//!         .with_task("printer", Printer)
34//!         .build()
35//!         .run();
36//!
37//!     supervisor.wait().await.unwrap();   // wait until every task finishes or is killed
38//!     Ok(())
39//! }
40//! ```
41//!
42//! ## What you get
43//!
44//! * **Automatic restarts** – failed tasks are relaunched with exponential back-off.
45//! * **Dynamic control** – add, restart, kill, or query tasks at runtime through a [`SupervisorHandle`].
46//! * **Configurable** – health-check interval, restart limits, back-off, dead-task threshold.
47//!
48//! ## Usage
49//!
50//! Build a supervisor with [`SupervisorBuilder`], call [`.build()`](SupervisorBuilder::build)
51//! to get a [`Supervisor`], then [`.run()`](Supervisor::run) to start it. This returns a
52//! [`SupervisorHandle`] you use to control things at runtime:
53//!
54//! | Method                          | Description                                          |
55//! | ------------------------------- | ---------------------------------------------------- |
56//! | `wait().await`                  | Block until the supervisor exits                     |
57//! | `add_task(name, task)`          | Register and start a new task                        |
58//! | `restart(name)`                 | Force-restart a task                                 |
59//! | `kill_task(name)`               | Stop a task permanently                              |
60//! | `get_task_status(name).await`   | Get a task's [`TaskStatus`]                          |
61//! | `get_all_task_statuses().await` | Get every task's status                              |
62//! | `shutdown()`                    | Stop all tasks and exit                              |
63//!
64//! The handle auto-shuts down the supervisor when all clones are dropped.
65//!
66//! ## Clone and restart behaviour
67//!
68//! Every task must implement `Clone`. The supervisor stores the **original**
69//! instance and clones it each time the task is started or restarted.
70//! Mutations made through `&mut self` in [`SupervisedTask::run`] only affect
71//! the running clone and are lost on restart.
72//!
73//! To share state across restarts, wrap it in an `Arc` (e.g. `Arc<AtomicUsize>`).
74//! Plain owned fields will always start from their original value. See the
75//! [`SupervisedTask`] docs for a full example.
76//!
77//! ## License
78//!
79//! [MIT](./LICENSE)
80
81pub use supervisor::{
82    builder::SupervisorBuilder,
83    handle::{SupervisorHandle, SupervisorHandleError},
84    Supervisor, SupervisorError,
85};
86pub use task::{SupervisedTask, TaskError, TaskResult, TaskStatus};
87
88mod supervisor;
89mod task;
90
91pub type TaskName = String;
task_supervisor/lib.rs

task_supervisor/
lib.rs
