# Module std::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 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:

ⓘ

    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.

## Modules

- failure_handling Experimental
  TBD

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

- Allocator Experimental
  An implementation of `Allocator` 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
  Signal a memory allocation error.
- realloc⚠
  Reallocate memory with the global allocator.

## Type Aliases

- LayoutErr Deprecated