ash_flare/lib.rs
1//! Fault-tolerant supervision trees for Rust with distributed capabilities.
2//!
3//! Build resilient systems that automatically recover from failures using supervisor trees,
4//! restart strategies, and distributed supervision inspired by Erlang/OTP.
5//!
6//! # Features
7//!
8//! - **Supervision Trees**: Hierarchical supervision with nested supervisors and workers
9//! - **Restart Strategies**: `OneForOne`, `OneForAll`, and `RestForOne` strategies
10//! - **Restart Policies**: `Permanent`, `Temporary`, and `Transient` restart behaviors
11//! - **Restart Intensity**: Configurable restart limits with sliding time windows
12//! - **Distributed**: Run supervisors across processes or machines via TCP/Unix sockets
13//! - **Generic Workers**: Trait-based worker system for any async workload
14//! - **Dynamic Management**: Add/remove children at runtime
15//! - **Structured Logging**: Built-in support for `slog` structured logging
16//! - **Mailbox System**: Optional message-passing for workers with string-based messages
17//!
18//! # Quick Start
19//!
20//! ```rust
21//! use ash_flare::{SupervisorSpec, SupervisorHandle, RestartPolicy, Worker};
22//! use async_trait::async_trait;
23//!
24//! struct Counter {
25//! id: u32,
26//! max: u32,
27//! }
28//!
29//! #[async_trait]
30//! impl Worker for Counter {
31//! type Error = std::io::Error;
32//!
33//! async fn run(&mut self) -> Result<(), Self::Error> {
34//! for i in 0..self.max {
35//! tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
36//! }
37//! Ok(())
38//! }
39//! }
40//!
41//! # #[tokio::main]
42//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
43//! // Build supervisor tree
44//! let spec = SupervisorSpec::new("root")
45//! .with_worker("counter-1", || Counter { id: 1, max: 5 }, RestartPolicy::Permanent)
46//! .with_worker("counter-2", || Counter { id: 2, max: 5 }, RestartPolicy::Permanent);
47//!
48//! // Start supervision tree
49//! let handle = SupervisorHandle::start(spec);
50//!
51//! // Query children
52//! let children = handle.which_children().await?;
53//!
54//! // Graceful shutdown
55//! handle.shutdown().await?;
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! # Restart Strategies
61//!
62//! - **OneForOne**: Restarts only the failed child (default)
63//! - **OneForAll**: Restarts all children if any child fails
64//! - **RestForOne**: Restarts the failed child and all children started after it
65//!
66//! # Examples
67//!
68//! See the [examples directory](https://github.com/gntem/ash-flare/tree/master/examples) for more:
69//!
70//! - `counter.rs` - Basic supervisor with multiple workers
71//! - `distributed.rs` - Network-distributed supervisors
72//! - `super_tree.rs` - Complex nested supervision trees
73
74#![deny(missing_docs)]
75#![warn(clippy::all)]
76#![warn(rust_2018_idioms)]
77
78#[macro_use]
79mod macros;
80
81mod restart;
82mod supervisor;
83mod supervisor_common;
84mod types;
85mod worker;
86
87pub mod distributed;
88pub mod mailbox;
89pub mod supervisor_stateful;
90
91// Re-export public API
92pub use restart::{RestartIntensity, RestartPolicy, RestartStrategy};
93pub use supervisor::{SupervisorError, SupervisorHandle, SupervisorSpec};
94pub use supervisor_stateful::{
95 StatefulSupervisorError, StatefulSupervisorHandle, StatefulSupervisorSpec,
96};
97pub use types::{ChildExitReason, ChildId, ChildInfo, ChildType, WorkerContext};
98pub use worker::{Worker, WorkerError};
99
100// Re-export mailbox types
101pub use mailbox::{Mailbox, MailboxConfig, MailboxHandle, SendError, TryRecvError, TrySendError};