lockfree_object_pool/lib.rs
1//! A thread-safe object pool collection with automatic return.
2//!
3//! Some implementations are lockfree :
4//! * [`LinearObjectPool`]
5//! * [`SpinLockObjectPool`]
6//!
7//! Other use std::Mutex :
8//! * [`MutexObjectPool`]
9//!
10//! And [`NoneObjectPool`] basic allocation without pool.
11//!
12//! ## Example
13//!
14//! The general pool creation looks like this for
15//! ```rust
16//! use lockfree_object_pool::LinearObjectPool;
17//!
18//! let pool = LinearObjectPool::<u32>::new(
19//! || Default::default(),
20//! |v| {*v = 0; });
21//!
22//! // And use the object pool
23//! let mut item = pool.pull();
24//! *item = 5;
25//! ```
26//! At the end of the scope item return in object pool.
27//! ## Multithreading
28//!
29//! All implementation support allocation/desallocation from on or more thread. You only need to wrap the pool in a [`std::sync::Arc`] :
30//!
31//! ```rust
32//! use lockfree_object_pool::LinearObjectPool;
33//! use std::sync::Arc;
34//!
35//! let pool = Arc::new(LinearObjectPool::<u32>::new(
36//! || Default::default(),
37//! |v| {*v = 0; }));
38//! ```
39//! ## Performance
40//!
41//! Global [report](https://evaillant.github.io/lockfree-object-pool/benches/criterion/report/index.html).
42//!
43//!
44//! #### Allocation
45//!
46//! ObjectPool | Duration in Monothreading (us) | Duration Multithreading (us)
47//! ------------| :----------------------------: | :--------------------------:
48//! [`NoneObjectPool`]|1.2848|0.62509
49//! [`MutexObjectPool`]|1.3107|1.5178
50//! [`SpinLockObjectPool`]|1.3106|1.3684
51//! [`LinearObjectPool`]|0.23732|0.38913
52//! [`crate 'sharded-slab'`]|1.6264|0.82607
53//! [`crate 'object-pool'`]|0.77533|0.26224
54//!
55//! Report [monothreading](https://evaillant.github.io/lockfree-object-pool/benches/criterion/allocation/report/index.html) and [multithreading](https://evaillant.github.io/lockfree-object-pool/benches/criterion/multi%20thread%20allocation/report/index.html)
56//!
57//! #### Forward Message between Thread
58//!
59//! ObjectPool | 1 Reader - 1 Writter (ns) | 5 Reader - 1 Writter (ns) | 1 Reader - 5 Writter (ns) | 5 Reader - 5 Writter (ns)
60//! -----------| :-----------------------: | :-----------------------: | :-----------------------: | :-----------------------:
61//! [`NoneObjectPool`]|529.75|290.47|926.05|722.35
62//! [`MutexObjectPool`]|429.29|207.17|909.88|409.99
63//! [`SpinLockObjectPool`]|34.277|182.62|1089.7|483.81
64//! [`LinearObjectPool`]|43.876|163.18|365.56|326.92
65//! [`crate 'sharded-slab'`]|525.82|775.79|966.87|1289.2
66//!
67//! Not supported by [`crate 'object-pool'`]
68//!
69//! Report [1-1](https://evaillant.github.io/lockfree-object-pool/benches/criterion//forward%20msg%20from%20pull%20(nb_writter_1%20nb_readder_1)/report/index.html), [5-1](https://evaillant.github.io/lockfree-object-pool/benches/criterion//forward%20msg%20from%20pull%20(nb_writter_1%20nb_readder_5)/report/index.html), [1-5](https://evaillant.github.io/lockfree-object-pool/benches/criterion//forward%20msg%20from%20pull%20(nb_writter_5%20nb_readder_1)/report/index.html) , [5-5](https://evaillant.github.io/lockfree-object-pool/benches/criterion//forward%20msg%20from%20pull%20(nb_writter_5%20nb_readder_5)/report/index.html)
70//!
71//! #### Desallocation
72//!
73//! ObjectPool | Duration in Monothreading (ns) | Duration Multithreading (ns)
74//! -----------| :----------------------------: | :--------------------------:
75//! [`NoneObjectPool`]|111.81|93.585
76//! [`MutexObjectPool`]|26.108|101.86
77//! [`SpinLockObjectPool`]|22.441|50.107
78//! [`LinearObjectPool`]|7.5379|41.707
79//! [`crate 'sharded-slab'`]|7.0394|10.283
80//! [`crate 'object-pool'`]|20.517|44.798
81//!
82//! Report [monothreading](https://evaillant.github.io/lockfree-object-pool/benches/criterion/free/report/index.html) and [multithreading](https://evaillant.github.io/lockfree-object-pool/benches/criterion/multi%20thread%20free/report/index.html)
83mod linear_object_pool;
84mod linear_owned_reusable;
85mod linear_page;
86mod linear_reusable;
87mod mutex_object_pool;
88mod mutex_owned_reusable;
89mod mutex_reusable;
90mod none_object_pool;
91mod none_reusable;
92mod page;
93mod spin_lock;
94mod spin_lock_object_pool;
95mod spin_lock_owned_reusable;
96mod spin_lock_reusable;
97
98pub use linear_object_pool::LinearObjectPool;
99pub use linear_owned_reusable::LinearOwnedReusable;
100pub use linear_reusable::LinearReusable;
101pub use mutex_object_pool::MutexObjectPool;
102pub use mutex_owned_reusable::MutexOwnedReusable;
103pub use mutex_reusable::MutexReusable;
104pub use none_object_pool::NoneObjectPool;
105pub use none_reusable::NoneReusable;
106pub use spin_lock_object_pool::SpinLockObjectPool;
107pub use spin_lock_owned_reusable::SpinLockOwnedReusable;
108pub use spin_lock_reusable::SpinLockReusable;