fastn_context/
lib.rs

1//! # fastn-context
2//!
3//! Type-safe async context propagation for Rust applications with hierarchical task management
4//! and graceful cancellation support.
5//!
6//! ## Overview
7//!
8//! `fastn-context` provides a robust context management system designed for async Rust applications.
9//! It enables hierarchical context propagation, graceful cancellation, and comprehensive status
10//! tracking across your application's task tree.
11//!
12//! ## Key Features
13//!
14//! - **Hierarchical Context Management**: Create parent-child relationships between contexts
15//! - **Graceful Cancellation**: Built on `tokio::CancellationToken` for clean shutdowns
16//! - **Status Tracking**: Monitor the state and progress of operations across your application
17//! - **Minimal Overhead**: Lightweight design with efficient async operations
18//! - **Easy Integration**: Simple APIs that integrate seamlessly with existing Rust async code
19//!
20//! ## Quick Start
21//!
22//! ### Basic Usage
23//!
24//! ```rust
25//! use fastn_context::Context;
26//! use tokio::time::{sleep, Duration};
27//!
28//! #[tokio::main]
29//! async fn main() {
30//!     let ctx = Context::builder("my-app").build();
31//!     
32//!     // Spawn a task with context
33//!     let child_ctx = ctx.child("worker");
34//!     tokio::spawn(async move {
35//!         // Your async work here
36//!         sleep(Duration::from_millis(100)).await;
37//!         println!("Work completed");
38//!     });
39//!
40//!     // Monitor status
41//!     let status = fastn_context::status().await;
42//!     println!("Active contexts: {}", status.contexts.len());
43//! }
44//! ```
45//!
46//! ### Using the `#[main]` Macro
47//!
48//! For applications that need automatic context setup:
49//!
50//! ```rust
51//! use fastn_context::main;
52//!
53//! #[main]
54//! async fn main() {
55//!     // Global context is automatically available
56//!     let ctx = fastn_context::global().await;
57//!     println!("App: {}", ctx.name());
58//! }
59//! ```
60//!
61//! ### Cancellation and Shutdown
62//!
63//! ```rust
64//! use fastn_context::Context;
65//! use tokio::select;
66//! use tokio::time::{sleep, Duration};
67//!
68//! #[tokio::main]
69//! async fn main() {
70//!     let ctx = Context::builder("my-app").build();
71//!     
72//!     let child_ctx = ctx.child("worker");
73//!     let token = child_ctx.cancellation_token();
74//!     
75//!     tokio::spawn(async move {
76//!         select! {
77//!             _ = token.cancelled() => {
78//!                 println!("Task was cancelled");
79//!             }
80//!             _ = sleep(Duration::from_secs(10)) => {
81//!                 println!("Task completed normally");
82//!             }
83//!         }
84//!     });
85//!     
86//!     // Cancel after 1 second
87//!     sleep(Duration::from_secs(1)).await;
88//!     child_ctx.cancel();
89//! }
90//! ```
91//!
92//! ## Architecture
93//!
94//! The crate is built around three main components:
95//!
96//! - [`Context`]: The core context type for hierarchical task management
97//! - [`ContextStatus`]: Status information and monitoring capabilities  
98//! - [`Status`]: Global status snapshots of the entire context tree
99//!
100//! ## Integration with fastn Applications
101//!
102//! This crate was extracted from the [fastn](https://github.com/fastn-stack/fastn) web framework
103//! to enable broader adoption of its context management patterns. It's designed to work
104//! seamlessly with fastn applications while being useful for any async Rust project.
105
106#![warn(unused_extern_crates)]
107#![deny(unused_crate_dependencies)]
108
109use tokio as _; // used by main macro
110use tokio_util as _; // used for cancellation tokens
111
112mod context;
113mod status;
114
115pub use context::{Context, ContextBuilder, global};
116pub use status::{ContextStatus, Status, status, status_with_latest};
117
118// Re-export main macro
119pub use fastn_context_macros::main;
fastn_context/lib.rs

fastn_context/
lib.rs
