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

zero_pool/
lib.rs
