std::alloc - Rust
Description: Memory allocation APIs.

## Module alloc

1.28.0 · Source
Expand description

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

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

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