allocator

import std::alloc::allocator; · source

The Allocator trait#

type trait Allocator {
    allocate(mut &this, layout: Layout) -> Result<NonNull<u8>, AllocError>;
    deallocate(mut &this, ptr: NonNull<u8>, layout: Layout) -> void;
    reallocate(mut &this, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout) -> Result<NonNull<u8>, AllocError>;
}

allocate returns uninitialized memory — write before you read. deallocate requires that the pointer came from a previous allocate on this allocator with a matching layout.

reallocate has a default: allocate, copy, free. An allocator that can grow a block in place should override it.

Collections take A: Allocator as a type parameter, so the storage strategy stays a caller decision instead of being baked into the container.

Implementors#

implement trait Allocator for struct GlobalAlloc

implement trait Allocator for struct Arena   // std::alloc::arena_alloc

implement trait Allocator for struct Pool   // std::alloc::pool

AllocError#

type struct AllocError {
    kind:   AllocErrorKind;
    layout: Layout;

    static new(kind: AllocErrorKind, layout: Layout) -> AllocError;
    describe(&this) -> Str;
}

Failures carry both a kind and the layout that was refused, and describe(&this) -> Str gives a short stable message — the same accessor every standard library error type exposes.

AllocErrorKind#

type enum AllocErrorKind {
    OutOfMemory;
    ZeroSized;
    Exhausted;
    InvalidLayout;
}

Kind	Meaning
OutOfMemory	The underlying allocator returned null: out of memory, or an address-space limit.
ZeroSized	The allocator refuses zero-sized requests. Handle the zero case before calling.
Exhausted	A bounded allocator (arena, pool) has no room for this request.
InvalidLayout	The layout is incompatible with this allocator — the wrong allocator for the request.

Trait implementations#

implement trait Display for struct AllocError   // std::fmt::display

implement trait Debug for struct AllocError   // std::fmt::display

GlobalAlloc#

type struct GlobalAlloc {
    static new() -> GlobalAlloc;
}

A zero-sized handle to the process-wide allocator; every instance dispatches through the same backend. Construct it with GlobalAlloc::new(). It is the default for every allocator-generic type in the library, which is what keeps the bare Box<T> spelling meaningful everywhere.

The backend is libc malloc by default and the segment heap in alloc::heap under the native_alloc config. Either way, when the compiler driver has published a per-target Arena, GlobalAlloc routes through it for the duration of a build — that is the compiler's own business and is inactive in user programs.

Trait implementations#

implement trait Allocator for struct GlobalAlloc

Growth policy#

function next_capacity(current: u64, required: u64, min_capacity: u64) -> u64;

next_capacity is the growth policy the containers share — double from current, never below min_capacity, and at least required. It is here rather than in collections so an allocator-aware type outside the stdlib can grow its buffers the same way.