Module 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 {
        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, 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.

---

1. Note that the Rust standard library internals may still directly call System when necessary (for example for the runtime support typically required to implement a global allocator, see re-entrance on GlobalAlloc for more details). ↩

Structs

Layout

Layout of a block of memory.

LayoutError

The LayoutError is returned when 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.

AllocErrorExperimental

The AllocError 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.

GlobalExperimental

The global memory allocator.

Traits

GlobalAlloc

A memory allocator that can be registered as the standard library’s default through the #[global_allocator] attribute.

AllocatorExperimental

An implementation of Allocator can allocate, grow, shrink, and deallocate arbitrary blocks of data described via Layout.

GlobalAllocatorExperimental

An Allocator that can be registered as the standard library’s default through the #[global_allocator] attribute.

Functions

alloc^⚠

Allocates memory with the global allocator.

alloc_zeroed^⚠

Allocates zero-initialized memory with the global allocator.

dealloc^⚠

Deallocates memory with the global allocator.

handle_alloc_error

Signals a memory allocation error.

realloc^⚠

Reallocates memory with the global allocator.

set_alloc_error_hookExperimental

Registers a custom allocation error hook, replacing any that was previously registered.

take_alloc_error_hookExperimental

Unregisters the current allocation error hook, returning it.

Type Aliases

LayoutErrDeprecated