orthotope 0.2.0

Arena-based memory allocator with per-thread caches and fixed size classes, designed for allocation-heavy workloads like ML inference and tensor pipelines
Documentation 
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

//! Orthotope is an arena-backed allocator with fixed size classes, per-thread caches,
//! a shared central pool, and a tracked large-allocation path.
//!
//! Use [`allocate`] and [`deallocate`] for the process-global convenience API, or
//! construct an [`Allocator`] plus one [`ThreadCache`] per participating thread for
//! direct instance-oriented use. Downstream binaries may also opt in to a
//! `#[global_allocator]` adapter via [`OrthotopeGlobalAlloc`].
//!
//! Only free live pointers returned by Orthotope. Debug builds detect some small-object
//! double frees, but same-arena pointer forgery and stale-pointer ABA cases are still
//! outside the allocator's guaranteed provenance boundary.

use std::cell::RefCell;
use std::sync::LazyLock;

/// Standalone allocator instances and the instance-oriented API.
pub mod allocator;
/// Process-global convenience allocation and free functions.
pub mod api;
/// Monotonic pre-mapped arena reservations.
pub mod arena;
/// Shared batch exchange between thread-local caches.
pub mod central_pool;
/// Allocator sizing and cache-tuning configuration.
pub mod config;
/// Typed initialization, allocation, and free failures.
pub mod error;
/// Intrusive free-list primitives used by allocator internals.
pub mod free_list;
/// Optional `GlobalAlloc` adapter for downstream binary opt-in.
pub mod global_alloc;
/// Allocation-header constants and pointer-layout helpers.
pub mod header;
/// Live tracking for allocations above the largest small class.
pub mod large_object;
/// Fixed request buckets and class sizing helpers.
pub mod size_class;
/// Allocator and thread-cache statistics snapshots.
pub mod stats;
/// Caller-owned per-thread cache state for the instance API.
pub mod thread_cache;

use crate::thread_cache::ThreadCacheHandle;
use crate::{allocator::Allocator as AllocatorType, error::InitError as InitErrorType};

static GLOBAL_ALLOCATOR: LazyLock<Result<AllocatorType, InitErrorType>> =
    LazyLock::new(|| AllocatorType::new(AllocatorConfig::default()));

thread_local! {
    static THREAD_CACHE: RefCell<Option<ThreadCacheHandle>> = const { RefCell::new(None) };
}

fn global_allocator() -> Result<&'static Allocator, &'static InitError> {
    GLOBAL_ALLOCATOR.as_ref()
}

pub(crate) fn try_with_thread_cache<R>(
    f: impl FnOnce(&Allocator, &mut ThreadCache) -> R,
) -> Result<Option<R>, &'static InitError> {
    let allocator = global_allocator()?;

    THREAD_CACHE
        .try_with(|cache| {
            let Ok(mut handle) = cache.try_borrow_mut() else {
                return Ok(None);
            };
            let handle = handle.get_or_insert_with(|| ThreadCacheHandle::new(allocator));
            Ok(Some(handle.with_parts(f)))
        })
        .unwrap_or(Ok(None))
}

pub use crate::allocator::Allocator;
pub use crate::api::{allocate, deallocate, deallocate_with_size, global_stats};
pub use crate::config::AllocatorConfig;
pub use crate::error::{AllocError, FreeError, InitError};
pub use crate::global_alloc::OrthotopeGlobalAlloc;
pub use crate::size_class::SizeClass;
pub use crate::stats::{AllocatorStats, SizeClassStats, ThreadCacheStats};
pub use crate::thread_cache::ThreadCache;