zero_pool/lib.rs
1//! # Zero-Pool: Ultra-High Performance Thread Pool
2//!
3//! A thread pool implementation designed for maximum performance through:
4//! - Zero-overhead task submission via raw pointers
5//! - Result-via-parameters pattern (no result transport)
6//! - Single global queue with optimal load balancing
7//! - Function pointer dispatch (no trait objects)
8//! - Lock-free queue operations with event-based worker coordination
9//!
10//! ## Safety
11//!
12//! This library achieves high performance through raw pointer usage. Users must ensure:
13//! - Parameter structs remain valid until `TaskFuture::wait()` completes
14//! - Result pointers remain valid until task execution finishes
15//! - Task functions are thread-safe and data-race free
16//! - No undefined behavior in unsafe task code
17//!
18//! ## Example
19//!
20//! ```rust
21//! use zero_pool::{ZeroPool, zp_define_task_fn, zp_write};
22//!
23//! struct MyTaskParams { value: u64, result: *mut u64 }
24//!
25//! zp_define_task_fn!(my_task, MyTaskParams, |params| {
26//! zp_write!(params.result, params.value * 2);
27//! });
28//!
29//! let pool = ZeroPool::new();
30//! let mut result = 0u64;
31//! let task_params = MyTaskParams { value: 42, result: &mut result };
32//! pool.submit_task(my_task, &task_params).wait();
33//! assert_eq!(result, 84);
34//! ```
35
36mod macros;
37mod padded_type;
38mod pool;
39mod queue;
40mod task_batch;
41mod task_future;
42mod worker;
43
44use std::sync::OnceLock;
45
46pub use pool::ZeroPool;
47
48pub use task_future::TaskFuture;
49
50static GLOBAL_ZP: OnceLock<ZeroPool> = OnceLock::new();
51
52/// Returns a reference to the lazily initialized global pool.
53///
54/// This is the simplest way to share a single pool across your application.
55/// The pool is created on first use using [`ZeroPool::new`].
56pub fn global_pool() -> &'static ZeroPool {
57 GLOBAL_ZP.get_or_init(ZeroPool::new)
58}
59
60/// Function pointer type for task execution
61///
62/// Tasks receive a raw pointer to their parameter struct and must
63/// cast it to the appropriate type for safe access.
64pub type TaskFnPointer = fn(*const ());
65
66/// Raw pointer to task parameter struct
67///
68/// This is type-erased for uniform storage but must be cast back
69/// to the original parameter type within the task function.
70pub type TaskParamPointer = *const ();