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 waiter;
43mod worker;
44
45pub use pool::ZeroPool;
46
47pub use task_future::TaskFuture;
48
49/// Function pointer type for task execution
50///
51/// Tasks receive a raw pointer to their parameter struct and must
52/// cast it to the appropriate type for safe access.
53pub type TaskFnPointer = fn(*const ());
54
55/// Raw pointer to task parameter struct
56///
57/// This is type-erased for uniform storage but must be cast back
58/// to the original parameter type within the task function.
59pub type TaskParamPointer = *const ();