1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
//! `cadalloc` — a minimal, configurable, embeddable allocator.
//!
//! `cadalloc` is a general-purpose allocator built around segregated free
//! lists. It targets multithreaded environments but deliberately does *not*
//! use thread-local free lists: the design goal is a small, predictable core
//! that is easy to embed and reason about, rather than the last few percent of
//! contended-allocation throughput.
//!
//! The crate is `#![no_std]` and assumes a **64-bit** target: addresses and
//! lengths are `u64` throughout, and the allocator hands out [`Slice`]s
//! (`{ ptr, len }`) rather than raw pointers.
//!
//! # Configuring an allocator
//!
//! All tuning lives in one trait, [`Config`]. Implementing it is the entire
//! configuration step — pick an [`Atomics`] backend and the four size-class
//! constants:
//!
//! ```
//! use cadalloc::{Config, CoreAtomics};
//!
//! struct MyConfig;
//!
//! impl Config for MyConfig {
//! type Atomics = CoreAtomics;
//!
//! const MIN_ALIGN: u64 = 16; // min alignment & linear class step
//! const LNR_FLOOR: u64 = 32; // smallest class
//! const EXP_FLOOR: u64 = 256; // linear -> exponential boundary
//! const EXP_CEIL: u64 = 65536; // largest class; above spills oversized
//! }
//!
//! // Optional but recommended: validate the constants at compile time.
//! const _: () = cadalloc::assert_config_valid::<MyConfig>();
//! ```
//!
//! See the [`config`] module for the size-class scheme and the heap-region
//! accessors, the [`atomic`] module for the atomic contract, and the
//! [`allocator`] module for the [`CadAlloc`] core.
//!
//! # Features
//!
//! - `alloc` *(off by default)* — implements [`core::alloc::GlobalAlloc`] for
//! [`CadAlloc`], so a configuration can serve as a program's
//! `#[global_allocator]`. See the `global` module (built with the feature)
//! for the alignment and initialization caveats.
// The crate is `no_std`, but its test builds (unit tests, the multithreaded
// stress test, and the loom model check) link and use `std`.
extern crate std;
pub use ;
pub use Atomics;
pub use CoreAtomics;
pub use ;
pub use ;
/// Computes the power of two `2^n` as a `u64`.
///
/// A thin wrapper over `1u64 << n`: it just spells the intent out at the call
/// site, which is handy for the power-of-two size-class constants a
/// [`Config`](crate::Config) is built from. It is `const`-evaluable, so it works
/// anywhere a constant is expected. `n` must be less than 64, or the shift
/// overflows (a compile error in `const` context).
///
/// # Examples
///
/// ```
/// use cadalloc::pow2;
///
/// const EXP_FLOOR: u64 = pow2!(8); // 256
/// const EXP_CEIL: u64 = pow2!(16); // 65536
/// assert_eq!(pow2!(0), 1);
/// assert_eq!(EXP_FLOOR, 256);
/// ```