taskvisor 0.6.0

Task supervisor for Tokio: restarts background tasks on failure with exponential backoff and jitter, graceful shutdown, and lifecycle events
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

//! # Runtime API
//!
//! This module contains the public runtime types:
//!
//! - [`Supervisor`] and [`SupervisorBuilder`] create and start a runtime.
//! - [`SupervisorHandle`] manages tasks in dynamic mode.
//! - [`SupervisorConfig`] sets runtime limits.
//! - [`TaskDefaults`] sets inherited task behavior.
//! - [`TaskWaiter`] returns a final [`TaskOutcome`].
//!
//! ## Runtime Paths
//!
//! State changes, final results, and observations use different paths:
//!
//! | Path                                                                     | Route                                                                           |
//! |--------------------------------------------------------------------------|---------------------------------------------------------------------------------|
//! | Direct `add*`, label operations, and identity stops without a controller | `SupervisorHandle` -> registry -> direct reply                                  |
//! | `submit*` and identity stops with a controller                           | `SupervisorHandle` -> controller -> registry when needed                        |
//! | Watched final result                                                     | registry or controller -> direct one-shot -> `TaskWaiter`                       |
//! | Observability                                                            | runtime components -> event bus -> event relay -> alive tracker and subscribers |
//!
//! The registry is the source of truth for registered identities and names.
//! Events are for observability and may be lost when consumers are slow.
//! Alive snapshots are based on those events. They can lag or miss state.
//!
//! ## When a Command Returns
//!
//! | Operation  | What the return value confirms                                                              |
//! |------------|---------------------------------------------------------------------------------------------|
//! | `add*`     | The registry accepted or rejected the task. The first attempt may not have started yet.     |
//! | `remove*`  | Whether this caller claimed the stop request. Registered task cleanup may still be running. |
//! | `cancel*`  | Known work reached terminal cleanup, unless the caller's explicit wait timeout expired.     |
//! | `shutdown` | Shared runtime cleanup finished. The result reports its final status.                       |
//!
//! Regular management methods wait for capacity in every bounded queue they use.
//! Their `try_*` versions fail fast at those queue boundaries.
//!
//! After a command is accepted, both forms may still wait for a direct decision or terminal cleanup.
//! [`SupervisorHandle::list`] reads authoritative registry membership.
//! [`SupervisorHandle::alive_snapshot`] and [`SupervisorHandle::is_alive`] are best-effort views built from events.
//!
//! ## Important Rules
//!
//! - [`Supervisor::run`] is single-shot and registers its initial tasks as one batch.
//! - Attempts for one registered task are sequential.
//! - New task admission closes when shutdown starts.
//! - Explicit shutdown returns after task, listener, and subscriber cleanup.
//! - Dropping the last public owner only starts best-effort cancellation.
//! - Event sequence numbers help sort observations, but do not prove causal order between concurrent tasks.

mod outcome;
pub use outcome::{TaskOutcome, TaskWaiter};

mod runtime;
pub(crate) use runtime::SupervisorCore;

mod builder;
pub use builder::SupervisorBuilder;

mod config;
pub use config::{ConfigError, SupervisorConfig};

mod task_defaults;
pub use task_defaults::TaskDefaults;

mod handle;
pub use handle::SupervisorHandle;

mod supervisor;
pub use supervisor::Supervisor;

mod owner;
pub(crate) use owner::RuntimeOwner;

pub(crate) mod panic_guard;

mod actor;
mod alive;
mod runner;
mod shutdown;

mod registry;
#[cfg(feature = "controller")]
pub(crate) use registry::{AddReplyRx, OutcomeTx, RemovalCompletion};