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
44pub use pool::ZeroPool;
45
46pub use task_future::TaskFuture;
47
48/// Function pointer type for task execution
49///
50/// Tasks receive a raw pointer to their parameter struct and must
51/// cast it to the appropriate type for safe access.
52pub type TaskFnPointer = fn(*const ());
53
54/// Raw pointer to task parameter struct
55///
56/// This is type-erased for uniform storage but must be cast back
57/// to the original parameter type within the task function.
58pub type TaskParamPointer = *const ();
59
60/// A work item containing a task function and its parameters
61///
62/// This tuple represents a single unit of work that can be
63/// executed by a worker thread.
64pub type TaskItem = (TaskFnPointer, TaskParamPointer);
65
66/// Convert a slice of uniform task parameters to work items
67///
68/// This is a performance optimization that pre-converts parameter
69/// pointers, avoiding repeated conversions during batch submission.
70/// Useful when you need to submit the same batch multiple times.
71///
72/// # Examples
73///
74/// ```rust
75/// use zero_pool::{ZeroPool, uniform_tasks_to_pointers, zp_define_task_fn, zp_write};
76///
77/// struct MyTaskStruct { value: u64, result: *mut u64 }
78///
79/// zp_define_task_fn!(my_task_fn, MyTaskStruct, |params| {
80///     zp_write!(params.result, params.value * 2);
81/// });
82///
83/// let pool = ZeroPool::new();
84/// let mut results = [0u64; 2];
85/// let tasks = [
86///     MyTaskStruct { value: 1, result: &mut results[0] },
87///     MyTaskStruct { value: 2, result: &mut results[1] }
88/// ];
89///
90/// // Convert once, reuse multiple times
91/// let work_items = uniform_tasks_to_pointers(my_task_fn, &tasks);
92///
93/// for _ in 0..5 {
94///     let future = pool.submit_raw_task_batch(&work_items);
95///     future.wait();
96/// }
97/// ```
98#[inline]
99pub fn uniform_tasks_to_pointers<T>(task_fn: TaskFnPointer, params_vec: &[T]) -> Vec<TaskItem> {
100    params_vec
101        .iter()
102        .map(|params| (task_fn, params as *const T as TaskParamPointer))
103        .collect()
104}
zero_pool/lib.rs

zero_pool/
lib.rs
