std::alloc - Rust
Description: API documentation for the Rust `alloc` mod in crate `std`.
Keywords: rust, rustlang, rust-lang, alloc

# 1.28.0[−][src]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 `cdylib`s and `staticlib`s 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);
    }

Run

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

ⓘThis example is not tested

    extern crate jemallocator;

    use jemallocator::Jemalloc;

    #[global_allocator]
    static GLOBAL: Jemalloc = Jemalloc;

    fn main() {}

Run

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

## Structs

AllocError | Experimental 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.
Global | Experimental The global memory allocator.
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.

## Traits

AllocRef | Experimental An implementation of `AllocRef` can allocate, grow, shrink, and deallocate arbitrary blocks of data described via `Layout`.
GlobalAlloc | A memory allocator that can be registered as the standard library’s default through the `#[global_allocator]` attribute.

## Functions

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