Expand description
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 Slices
({ 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) — implementscore::alloc::GlobalAllocforCadAlloc, so a configuration can serve as a program’s#[global_allocator]. See theglobalmodule (built with the feature) for the alignment and initialization caveats.
Re-exports§
pub use allocator::CadAlloc;pub use allocator::InitError;pub use allocator::VerifyError;pub use atomic::Atomics;pub use atomic::CoreAtomics;pub use config::Config;pub use config::assert_config_valid;pub use config::const_heap_base;pub use config::const_heap_size;pub use slice::Slice;pub use slice::SliceView;
Modules§
- allocator
- The allocator core: size-class mapping, block headers, and the
alloc/freefast paths. - atomic
- The atomic primitives the allocator is built on.
- config
- The configuration surface: the single trait a user implements to stand up an allocator, plus compile-time validation of its constants.
- ffi
- Exporting a
cadallocallocator to C and other non-Rust callers. - global
GlobalAllocadapter, behind theallocfeature.- slice
- The two memory-region types the allocator traffics in.
Macros§
- export_
c_ api - Emits unmangled
extern "C"entry points for one concreteConfig. - pow2
- Computes the power of two
2^nas au64.