Module std::alloc

Memory allocation APIs

In a given program, the standard library has one “global” memory allocator that is used for example by Box<T> and Vec<T>.

Currently the default global allocator is unspecified. Libraries, however, like cdylibs and staticlibs are guaranteed to use the System by default.

The #[global_allocator] attribute

This attribute allows configuring the choice of global allocator. You can use this to implement a completely custom global allocator to route all default allocation requests to a custom object.

use std::alloc::{GlobalAlloc, System, Layout};

struct MyAllocator;

unsafe impl GlobalAlloc for MyAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        System.alloc(layout)
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        System.dealloc(ptr, layout)
    }
}

#[global_allocator]
static GLOBAL: MyAllocator = MyAllocator;

fn main() {
    // This `Vec` will allocate memory through `GLOBAL` above
    let mut v = Vec::new();
    v.push(1);
}

The attribute is used on a static item whose type implements the GlobalAlloc trait. This type can be provided by an external library:

extern crate jemallocator;

use jemallocator::Jemalloc;

#[global_allocator]
static GLOBAL: Jemalloc = Jemalloc;

fn main() {}

The #[global_allocator] can only be used once in a crate or its recursive dependencies.

Structs

Layout	Layout of a block of memory.
LayoutErr	The parameters given to Layout::from_size_align or some other Layout constructor do not satisfy its documented constraints.
System	The default memory allocator provided by the operating system.
AllocErr	Experimental The AllocErr error indicates an allocation failure that may be due to resource exhaustion or to something wrong when combining the given input arguments with this allocator.
CannotReallocInPlace	Experimental The CannotReallocInPlace error is used when grow_in_place or shrink_in_place were unable to reuse the given memory block for a requested layout.
Excess	Experimental Represents the combination of a starting address and a total capacity of the returned block.
Global	Experimental The global memory allocator.

Traits

GlobalAlloc	A memory allocator that can be registered as the standard library’s default though the #[global_allocator] attributes.
Alloc	Experimental An implementation of Alloc can allocate, reallocate, and deallocate arbitrary blocks of data described via Layout.

Functions

alloc⚠	Allocate memory with the global allocator.
alloc_zeroed⚠	Allocate zero-initialized memory with the global allocator.
dealloc⚠	Deallocate memory with the global allocator.
handle_alloc_error	Abort on memory allocation error or failure.
realloc⚠	Reallocate memory with the global allocator.
set_alloc_error_hook	Experimental Registers a custom allocation error hook, replacing any that was previously registered.
take_alloc_error_hook	Experimental Unregisters the current allocation error hook, returning it.