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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
//! # taskvisor
//!
//! **Taskvisor** is a lightweight task orchestration library for Rust.
//!
//! It provides primitives to define, supervise, and restart async tasks
//! with configurable policies. The crate is designed as a building block
//! for higher-level orchestrators and agents.
//!
//! ## Architecture
//! ### Overview
//!
//! ```text
//! ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
//! │ TaskSpec │ │ TaskSpec │ │ TaskSpec │
//! │(user task #1)│ │(user task #2)│ │(user task #3)│
//! └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
//! ▼ ▼ ▼
//! ┌───────────────────────────────────────────────────────────────────┐
//! │ Supervisor (runtime orchestrator) │
//! │ - Bus (broadcast events) │
//! │ - AliveTracker (tracks task state with sequence numbers) │
//! │ - SubscriberSet (fans out to user subscribers) │
//! │ - Registry (manages active tasks by name) │
//! └──────┬──────────────────┬──────────────────┬───────────────┬──────┘
//! ▼ ▼ ▼ │
//! ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
//! │ TaskActor │ │ TaskActor │ │ TaskActor │ │
//! │ (retry loop) │ │ (retry loop) │ │ (retry loop) │ │
//! └┬─────────────┘ └┬─────────────┘ └┬─────────────┘ │
//! │ │ │ │
//! │ Publishes │ Publishes │ Publishes │
//! │ Events: │ Events: │ Events: │
//! │ - TaskStarting │ - TaskStarting │ - TaskStarting │
//! │ - TaskFailed │ - TaskStopped │ - TimeoutHit │
//! │ - BackoffSched. │ - ActorExhausted │ - ... │
//! │ │ │ │
//! ▼ ▼ ▼ ▼
//! ┌───────────────────────────────────────────────────────────────────┐
//! │ Bus (broadcast channel) │
//! │ (capacity: SupervisorConfig::bus_capacity) │
//! └─────────────────────────────────┬─────────────────────────────────┘
//! ▼
//! ┌────────────────────────┐
//! │ subscriber_listener │
//! │ (in Supervisor) │
//! └───┬────────────────┬───┘
//! ▼ ▼
//! AliveTracker SubscriberSet
//! (sequence-based) (per-sub queues)
//! ┌─────────┼─────────┐
//! ▼ ▼ ▼
//! worker1 worker2 workerN
//! ▼ ▼ ▼
//! sub1.on sub2.on subN.on
//! _event() _event() _event()
//! ```
//!
//! ### Lifecycle
//!
//! ```text
//! TaskSpec ──► Supervisor ──► Registry ──► TaskActor::run()
//!
//! loop {
//! ├─► attempt += 1
//! ├─► acquire semaphore (optional, cancellable)
//! ├─► publish TaskStarting{ task, attempt }
//! ├─► run_once(task, timeout, attempt)
//! │ │
//! │ ├─ Ok ──► publish TaskStopped
//! │ │ ├─ RestartPolicy::Never ─► ActorExhausted, exit
//! │ │ ├─ RestartPolicy::OnFailure ─► ActorExhausted, exit
//! │ │ └─ RestartPolicy::Always ─► reset delay, continue
//! │ │
//! │ └─ Err ──► publish TaskFailed{ task, error, attempt }
//! │ ├─ RestartPolicy::Never ─► ActorExhausted, exit
//! │ └─ RestartPolicy::OnFailure/Always:
//! │ ├─ compute delay = backoff.next(backoff_attempt)
//! │ ├─ publish BackoffScheduled{ delay, attempt }
//! │ ├─ sleep(delay) (cancellable)
//! │ └─ continue
//! │
//! └─ exit conditions:
//! - runtime_token cancelled (OS signal or explicit remove)
//! - RestartPolicy forbids continuation ─► ActorExhausted
//! - Fatal error ─► ActorDead
//! - semaphore closed
//! }
//!
//! On exit: actor cleanup removes from Registry (if PolicyExhausted/Fatal)
//! ```
//!
//! ## Features
//!
//! | Area | Description | Key types / traits |
//! |-------------------|------------------------------------------------------------------------|----------------------------------------|
//! | **Subscriber API**| Hook into task lifecycle events (logging, metrics, custom subscribers).| [`Subscribe`] |
//! | **Policies** | Configure restart/backoff strategies for tasks. | [`RestartPolicy`], [`BackoffPolicy`] |
//! | **Supervision** | Manage groups of tasks and their lifecycle. | [`Supervisor`], [`SupervisorHandle`] |
//! | **Errors** | Typed errors for orchestration and task execution. | [`TaskError`], [`RuntimeError`] |
//! | **Tasks** | Define tasks as functions or specs, easy to compose and run. | [`TaskRef`], [`TaskFn`], [`TaskSpec`] |
//! | **Configuration** | Centralize runtime settings. | [`SupervisorConfig`] |
//!
//! ## Optional features
//!
//! - `logging`: exports a simple built-in [`LogWriter`] _(demo/reference only)_.
//! - `controller`: exposes controller runtime and admission types.
//!
//! ## Example
//!
//! ```rust
//! use taskvisor::prelude::*;
//!
//! #[tokio::main(flavor = "current_thread")]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let sup = Supervisor::new(SupervisorConfig::default(), vec![]);
//!
//! // Define a simple task that runs once and exits
//! let hello: TaskRef = TaskFn::arc("hello", |ctx: CancellationToken| async move {
//! if ctx.is_cancelled() { return Ok(()); }
//! println!("Hello from task!");
//! Ok(())
//! });
//!
//! // One-shot task (runs once, never restarts)
//! let spec = TaskSpec::once(hello);
//!
//! sup.run(vec![spec]).await?;
//! Ok(())
//! }
//! ```
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Subscribe;
pub use ;
pub use LogWriter;