A memory allocator manages heap storage for values whose size or lifetime calls for dynamic allocation. In Rust, Vec and Box request heap storage without requiring you to manage the allocator directly. Stack allocation is generally faster; on memory-constrained systems, avoiding a heap may be preferable. section 5.1 section 5.10
Implement the Allocator trait when a data structure needs custom allocation behavior. Its required methods are allocate, which receives a Layout and returns a memory region or AllocError, and unsafe deallocate, which releases a region using its layout. The trait supplies defaults for zeroed allocation, growth, and shrinking; default growth and shrinking allocate, copy, then release the old region. Allocation code commonly requires unsafe operations. section 5.8.1
Listing 5.11 Code for a pass-through allocator
#![feature(allocator_api)]
use std::alloc::{AllocError, Allocator, Global, Layout};
use std::ptr::NonNull;
pub struct PassThruAllocator;
unsafe impl Allocator for PassThruAllocator {
fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError> {
Global.allocate(layout)
}
unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout) {
Global.deallocate(ptr, layout)
}
}
A minimal pass-through implementation delegates both required methods to Global; it provides a starting point before changing allocation behavior. section 5.8.1
Use an allocator with Vec
Construct a vector with Vec::with_capacity_in(10, BasicAllocator), then push values into it. The demonstrated BasicAllocator calls C malloc and free. Treat that listing as a basic example, not a portable template: Layout specifies both size and alignment, and both must be handled. These allocator API examples require a nightly toolchain and #![feature(allocator_api)]. section 5.8.1
Custom allocation can serve a single data structure rather than the entire program. A protected-memory allocator, for example, obtains page-aligned storage through platform-specific functions, places protected regions before and after the active region, and returns a slice of the active region. This supports memory protection for sensitive data such as secret keys. Its deallocation path must account for the surrounding regions. section 5.8.2
Choose the scope first: use Allocator for per-structure behavior; GlobalAlloc is another customization API, including for embedded systems that need a heap. If dynamic allocation is unnecessary, fixed-size data structures from heapless avoid it altogether. section 5.8.2 section 2.12.1
