The tracking issue for this feature is: #27389

Rust programs may need to change the allocator that they're running with from time to time. This use case is distinct from an allocator-per-collection (e.g. a Vec with a custom allocator) and instead is more related to changing the global default allocator, e.g. what Vec<T> uses by default.

Currently Rust programs don't have a specified global allocator. 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 allocator" which means something like malloc on Unixes and HeapAlloc on Windows.

The #[global_allocator] attribute, however, allows configuring this choice. You can use this to implement a completely custom global allocator to route all default allocation requests to a custom object. Defined in RFC 1974 usage looks like:

#![feature(global_allocator, allocator_api, heap_api)]

use std::heap::{Alloc, System, Layout, AllocErr};

struct MyAllocator;

unsafe impl<'a> Alloc for &'a MyAllocator {
    unsafe fn alloc(&mut self, layout: Layout) -> Result<*mut u8, AllocErr> {
        System.alloc(layout)
    }

    unsafe fn dealloc(&mut 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);
}

And that's it! The #[global_allocator] attribute is applied to a static which implements the Alloc trait in the std::heap module. Note, though, that the implementation is defined for &MyAllocator, not just MyAllocator. You may wish, however, to also provide Alloc for MyAllocator for other use cases.

A crate can only have one instance of #[global_allocator] and this instance may be loaded through a dependency. For example #[global_allocator] above could have been placed in one of the dependencies loaded through extern crate.

Note that Alloc itself is an unsafe trait, with much documentation on the trait itself about usage and for implementors. Extra care should be taken when implementing a global allocator as well as the allocator may be called from many portions of the standard library, such as the panicking routine. As a result it is highly recommended to not panic during allocation and work in as many situations with as few dependencies as possible as well.