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 {
        unsafe { System.alloc(layout) }
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        unsafe { 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:

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.

The global allocator is invoked via the functions in this module ([alloc][crate::alloc::alloc], alloc_zeroed, dealloc, realloc). Note, however, that invoking those functions is not equivalent to directly invoking the underlying methods on the declared global allocator! See the documentation of those functions for details.