heapless/pool.rs
1//! Memory and object pools
2//!
3//! # Target support
4//!
5//! This module / API is only available on these compilation targets:
6//!
7//! - ARM architectures which instruction set include the LDREX, CLREX and STREX instructions, e.g.
8//! `thumbv7m-none-eabi` but not `thumbv6m-none-eabi`
9//! - 32-bit x86, e.g. `i686-unknown-linux-gnu`
10//!
11//! # Benchmarks
12//!
13//! - compilation settings
14//! - `codegen-units = 1`
15//! - `lto = 'fat'`
16//! - `opt-level = 'z'`
17//! - compilation target: `thumbv7em-none-eabihf`
18//! - CPU: ARM Cortex-M4F
19//!
20//! - test program:
21//!
22//! ``` no_run
23//! use heapless::box_pool;
24//!
25//! box_pool!(P: ()); // or `arc_pool!` or `object_pool!`
26//!
27//! bkpt();
28//! let res = P.alloc(());
29//! bkpt();
30//!
31//! if let Ok(boxed) = res {
32//! bkpt();
33//! drop(boxed);
34//! bkpt();
35//! }
36//! # fn bkpt() {}
37//! ```
38//!
39//! - measurement method: the cycle counter (CYCCNT) register was sampled each time a breakpoint
40//! (`bkpt`) was hit. the difference between the "after" and the "before" value of CYCCNT yields the
41//! execution time in clock cycles.
42//!
43//! | API | clock cycles |
44//! |------------------------------|--------------|
45//! | `BoxPool::alloc` | 23 |
46//! | `pool::boxed::Box::drop` | 23 |
47//! | `ArcPool::alloc` | 28 |
48//! | `pool::arc::Arc::drop` | 59 |
49//! | `ObjectPool::request` | 23 |
50//! | `pool::object::Object::drop` | 23 |
51//!
52//! Note that the execution time won't include `T`'s initialization nor `T`'s destructor which will
53//! be present in the general case for `Box` and `Arc`.
54
55mod treiber;
56
57pub mod arc;
58pub mod boxed;
59pub mod object;