relay_threading/
lib.rs

1//! # Relay Threading
2//!
3//! This module provides a robust threading framework for Relay, designed to efficiently manage and execute
4//! asynchronous workloads. At its core is a thread-based asynchronous task pool that offers:
5//!
6//! - **Flexible Configuration**: Fine-tune thread counts, naming patterns, panic handling strategies,
7//!   and concurrency limits through a builder pattern.
8//! - **Task Multiplexing**: Distribute tasks across dedicated worker threads.
9//! - **Panic Recovery**: Built-in mechanisms to gracefully handle and recover from panics, both at the
10//!   thread and individual task level
11//! - **Tokio Integration**: Seamlessly integrates with Tokio runtime for async task execution
12//!
13//! ## Concurrency Model
14//!
15//! The pool maintains a set of dedicated worker threads, each capable of executing multiple async tasks
16//! concurrently up to a configurable limit. This architecture ensures efficient resource utilization
17//! while preventing any single thread from becoming overwhelmed.
18//!
19//! The pool maintains a bounded queue with a capacity of twice the number of worker threads. This
20//! design allows new tasks to be queued while existing ones are being processed, ensuring smooth
21//! task handoff between producers and consumers. The bounded nature of the queue provides natural
22//! backpressure - when workers are overwhelmed, task submission will block until capacity becomes
23//! available, preventing resource exhaustion.
24//!
25//! ## Usage Example
26//!
27//! ```rust
28//! use relay_threading::{AsyncPoolBuilder, AsyncPool};
29//! use tokio::runtime::Runtime;
30//!
31//! // Create a runtime (for example purposes, create one inline)
32//! let runtime_handle = Runtime::new().unwrap();
33//!
34//! // Build an async pool with 4 threads and a max of 100 concurrent tasks per thread
35//! let pool: AsyncPool<_> = AsyncPoolBuilder::new(runtime_handle.handle().clone())
36//!     .num_threads(4)
37//!     .max_concurrency(100)
38//!     .build()
39//!     .expect("Failed to build async pool");
40//!
41//! // Schedule a task to be executed by the pool
42//! pool.spawn(async {
43//!     // Place your asynchronous task logic here
44//! });
45//! ```
46//!
47//! ## Error Handling
48//!
49//! Both the async pool and its task multiplexer support custom panic handlers, allowing graceful
50//! recovery from panics in either thread execution or individual tasks.
51
52mod builder;
53mod metrics;
54mod multiplexing;
55mod pool;
56
57pub use self::builder::*;
58pub use self::metrics::*;
59pub use self::pool::*;