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

# Module std::alloc 1.28.0[−][src]

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. The compiler may link to a version of jemalloc on some platforms, but this is not guaranteed. 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

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.
AllocErr | [ Experimental ] The `AllocErr` 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.
CannotReallocInPlace | [ Experimental ] The `CannotReallocInPlace` error is used when `grow_in_place` or `shrink_in_place` were unable to reuse the given memory block for a requested layout.
Excess | [ Experimental ] Represents the combination of a starting address and a total capacity of the returned block.
Global | [ Experimental ] The global memory allocator.

## Traits

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

## Functions

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)