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. The compiler may link to a version of jemalloc on some platforms, but this is not guaranteed. 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 jemallacator::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.

Enums

CollectionAllocErr

[ Experimental ] Augments AllocErr with a CapacityOverflow variant.

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.