# Rust global allocator API
Date: 2026-08-15
Release: 0.3.1
Status: stable `GlobalAlloc` surface; experimental allocator implementation
## Installation
Declare one process allocator in the final executable:
```rust
use bomalloc::BoGlobalAllocator;
#[global_allocator]
static GLOBAL: BoGlobalAllocator = BoGlobalAllocator::new();
```
Libraries should normally expose allocation-neutral APIs and leave the global
allocator choice to the executable.
## Public surface
`BoGlobalAllocator` implements every stable `std::alloc::GlobalAlloc` entry:
| `alloc` | Lazily initializes bomalloc and returns null on failure. |
| `alloc_zeroed` | Allocates and zeros the requested byte range. |
| `dealloc` | Releases bomalloc pointers and safely routes bootstrap System pointers. |
| `realloc` | Preserves `min(old_size, new_size)` bytes; bootstrap pointers use `System::realloc`. |
It also exposes guarded management operations:
```rust
use bomalloc::{BoGlobalAllocator, TrimMode};
# static GLOBAL: BoGlobalAllocator = BoGlobalAllocator::new();
let snapshot = GLOBAL.stats()?;
let trimmed = GLOBAL.trim(TrimMode::Excess)?;
GLOBAL.validate()?;
# Ok::<(), bomalloc::BoAllocError>(())
```
The internal explicit allocator is intentionally not exposed through the global
adapter: diagnostic and maintenance calls must keep the recursion guard active
for their complete operation.
## Static configuration
`Config::new()` is const and matches `Config::default()`:
```rust
use bomalloc::{BoGlobalAllocator, Config};
const CONFIG: Config = Config {
random_seed: Some(0x5eed),
..Config::new()
};
#[global_allocator]
static GLOBAL: BoGlobalAllocator = BoGlobalAllocator::with_config(CONFIG);
```
For a thread-local generational runtime, `Config::runtime_gc()` is also const:
```rust
use bomalloc::{BoGlobalAllocator, Config};
#[global_allocator]
static GLOBAL: BoGlobalAllocator =
BoGlobalAllocator::with_config(Config::runtime_gc());
```
An invalid configuration does not make the adapter unusable: allocation falls
back to `System`, while `initialize()`, `stats()`, and `trim()` report the stored
initialization error.
## Bootstrap and recursion
Constructing the internal allocator requires Rust allocation for `Arc`, tree
payloads, and epoch metadata. Lazy initialization can therefore recursively
reach the installed global symbols. A const TLS recursion flag routes those
internal bootstrap allocations to `std::alloc::System`.
Normal user allocations use bomalloc after initialization. Internal System
objects are created and destroyed while the recursion guard is active, so
ordinary deallocation does not need a general origin search.
## Native TLS teardown
Rust's destructor-bearing `thread_local!` registry may allocate while registering
a destructor, which is unsafe during allocator bootstrap. Bomalloc therefore
stores allocator TLS through operating-system keys:
- Windows Fiber Local Storage;
- Linux pthread keys.
The native cache slot itself uses `System`. Its callback clears the key before
destroying the cache so recursive access cannot observe a half-destroyed value.
Once allocator TLS teardown begins, later Rust TLS destructors may still release
bomalloc objects; owner-local caching is skipped and blocks use the shared span
publication path.
## Safety contract
The adapter inherits `GlobalAlloc`'s contract:
- return each non-null pointer to the same installed allocator;
- use its exact original `Layout`, unless reallocation succeeded;
- release it exactly once and never access it afterward;
- treat null as allocation failure;
- do not unwind through allocator entry points;
- do not make optimizer-visible allocation counts part of program behavior.
A static global adapter lives through process termination, at which point the
operating system reclaims remaining reservations. Explicit `BoAllocator` handles
have a stricter lifetime contract: their final handle must outlive every non-zero
allocation.
## Scope and limitations
- The stable per-container `Allocator` trait is not implemented because it is
still unstable on the Rust 1.86 baseline.
- Only x86-64 Windows and Linux are supported.
- The adapter is tested with cross-thread objects, realloc, Rust TLS teardown,
invalid-configuration fallback, statistics, validation, and trim.
- Current benchmark evidence is reported in
[Mature allocator benchmark](mature-benchmark-results.md) and
[Runtime-shaped workloads](runtime-workload-results.md), not duplicated here.
- The allocator remains experimental and unaudited.