bomalloc 0.3.1

A fragmentation-aware experimental allocator built around address-span ownership
Documentation
# 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:

| Entry | Behavior |
|---|---|
| `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.