taskvisor 0.4.1

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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! # Runtime core.
//!
//! This module contains the taskvisor runtime implementation.
//!
//! Public API:
//!
//! | File            | Role                                      |
//! |-----------------|-------------------------------------------|
//! | `supervisor.rs` | Public facade and composition root        |
//! | `handle.rs`     | Dynamic task management API               |
//! | `config.rs`     | Runtime defaults and limits               |
//! | `outcome.rs`    | Guaranteed task completion results        |
//! | `builder.rs`    | Runtime construction                      |
//!
//! Internal runtime:
//!
//! | File             | Role                                      |
//! |------------------|-------------------------------------------|
//! | `runtime.rs`     | Owns Bus, Registry, subscribers, shutdown |
//! | `registry.rs`    | Owns active task actors and add/remove    |
//! | `actor.rs`       | Runs one task with restart/backoff policy |
//! | `runner.rs`      | Executes one task attempt                 |
//! | `alive.rs`       | Best-effort live-task snapshot            |
//! | `shutdown.rs`    | OS signal handling                        |
//! | `panic_guard.rs` | Panic boundary for long-lived listeners   |
//!
//! ## Planes
//!
//! taskvisor has three important runtime planes:
//!
//! ```text
//! Management plane:
//!   SupervisorHandle ──► SupervisorCore ──mpsc──► Registry
//!
//! Event plane:
//!   runtime components ──broadcast──► subscriber_listener ──► Subscribe impls
//!
//! Completion plane:
//!   Registry ──oneshot──► TaskWaiter
//! ```
//!
//! The management plane uses an mpsc command channel. Add/remove commands are not delivered through the lossy event bus.
//! The event plane is best-effort and used for logs, metrics, snapshots, and subscriber integrations. Slow consumers can lag and miss events.
//! The completion plane is used by `add_and_watch` and `submit_and_watch`. It is the authoritative final result for one task run.
//!
//! ## Main Flow
//!
//! ```text
//! Supervisor::run(tasks)
//!   ├─ start subscriber listener
//!   ├─ start registry listener
//!   ├─ send initial Add commands
//!   ├─ wait until initial tasks are accepted/rejected
//!   └─ wait for OS shutdown signal or natural completion
//!
//! Supervisor::serve()
//!   ├─ start listeners
//!   └─ return SupervisorHandle
//! ```
//!
//! ## Events
//!
//! Events are published by:
//!
//! - `SupervisorCore`: add/remove/shutdown requests and final runtime verdicts.
//! - `TaskActor`: attempt starts, retry scheduling, actor terminal state.
//! - `SubscriberSet`: subscriber overflow and panic diagnostics.
//! - `Registry`: task added/removed confirmations.
//! - `runner`: per-attempt result events.
//!
//! `AllStoppedWithinGrace` can be emitted after explicit shutdown or after natural completion when all cleanup joins finish within the grace period.
//!
//! ## Notes
//!
//! - `Supervisor::run` is single-shot for one supervisor instance.
//! - Attempts within one `TaskActor` are sequential; the same actor never runs two attempts in parallel.
//! - Event sequence numbers are useful for stale-event filtering and sorting, but they are not a causal ordering guarantee across concurrent producers.
//! - A panic in a long-lived listener is caught and reported as a diagnostic event instead of silently killing the control loop.

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::SupervisorConfig;

mod handle;
pub use handle::SupervisorHandle;

mod supervisor;
pub use supervisor::Supervisor;

pub(crate) mod panic_guard;

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

mod registry;
#[cfg(feature = "controller")]
pub(crate) use registry::OutcomeTx;