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 take exactly one parameter (usually the task parameter struct)
16//! - Task functions are thread-safe and data-race free
17//! - No undefined behavior in unsafe task code
18//!
19//! This API is unsafe-by-contract and performs no runtime validation of these invariants.
20//!
21//! ## Example
22//!
23//! ```rust
24//! use zero_pool::ZeroPool;
25//!
26//! struct MyTaskParams { value: u64, result: *mut u64 }
27//!
28//! fn my_task(params: &MyTaskParams) {
29//! unsafe { *params.result = params.value * 2; }
30//! }
31//!
32//! let pool = ZeroPool::new();
33//! let mut result = 0u64;
34//! let task_params = MyTaskParams { value: 42, result: &mut result };
35//! pool.submit_task(my_task, &task_params).wait();
36//! assert_eq!(result, 84);
37//! ```
38
39mod padded_type;
40mod pool;
41mod queue;
42mod task_batch;
43mod task_future;
44mod worker;
45
46use std::ptr::NonNull;
47use std::sync::OnceLock;
48
49pub use pool::ZeroPool;
50pub use task_future::TaskFuture;
51
52static GLOBAL_ZP: OnceLock<ZeroPool> = OnceLock::new();
53
54/// Returns a reference to the lazily initialized global pool.
55///
56/// This is the simplest way to share a single pool across your application.
57/// The pool is created on first use using [`ZeroPool::new`].
58#[inline]
59pub fn global_pool() -> &'static ZeroPool {
60 GLOBAL_ZP.get_or_init(ZeroPool::new)
61}
62
63/// Function pointer type for task execution
64///
65/// Tasks receive a non-null pointer to their parameter struct and must
66/// cast it to the appropriate type for safe access.
67pub(crate) type TaskFnPointer = fn(NonNull<u8>);
68
69/// Non-null pointer to task parameter struct
70///
71/// This is type-erased for uniform storage but must be cast back
72/// to the original parameter type within the task function.
73pub(crate) type TaskParamPointer = NonNull<u8>;