alloc
Everything that touches the heap lives in alloc. It gives you three things: a description of a memory request (Layout), a trait that anything serving those requests implements (Allocator), and the owning pointers built on top — Box, Rc, Arc — plus two allocation strategies, Arena and Pool, that you can substitute for the default.
public module alloc::layout;
public module alloc::allocator;
public module alloc::box;
public module alloc::arena;
public module alloc::arena_alloc;
public module alloc::pool;
public module alloc::heap;
public module alloc::rc;
public module alloc::arc;Types here own storage. Each one exposes drop(mut &this), and its documentation names who is responsible for calling it. In practice the compiler synthesises the call at scope exit; a manual .drop() remains available for early release.
| File | What it holds | Import |
|---|---|---|
layout | Layout, a size and an alignment | import std::alloc::layout; |
allocator | The Allocator trait, AllocError, GlobalAlloc | import std::alloc::allocator; |
box | Box<T, A>, unique heap ownership | (prelude) |
rc | Rc<T, A> and its Weak, single-threaded sharing | (prelude) |
arc | Arc<T, A> and its Weak, cross-thread sharing | import std::alloc::arc; |
arena | Arena, bump allocation with bulk release | import std::alloc::arena; |
pool | Pool, fixed-size slots on a free list | import std::alloc::pool; |
Two files have no page of their own. alloc::arena_alloc holds Arena's Allocator and Drop impls — split out because allocator imports arena and the module graph rejects cycles; they are listed on the arena page. alloc::heap is the mmap-backed segment heap behind GlobalAlloc when the compiler is built with native_alloc; you never call it directly.
public function name() { ... }
public:Visible to any module that imports this one - the default for top-level items and for struct fields, so it is mostly written to be explicit. public: opens a visibility block that groups the members after it.
public module collections::array;In a directory's _module.cryo aggregator, lists a submodule and whether it is public. Importing the directory's namespace sees only the modules declared public here.
namespace std::alloc::arena_alloc;Arena trait impls: Allocator and Drop for Arena.
namespace std::alloc::heap;heap: the mmap-backed process heap (Low-Level Plan Stage 3).
namespace std::alloc::rc;Rc<T, A>: single-threaded reference counting, with weak references.
module pagetype struct Layout {
size: u64;
alignment: u64;
}Layout: size + alignment of a memory block.
std::alloc::layouttype trait Allocator {
allocate(mut &this, layout: Layout) -> Result<NonNull<u8>, AllocError>;
deallocate(mut &this, ptr: NonNull<u8>, layout: Layout) -> void;
reallocate(mut &this, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout) -> Result<NonNull<u8>, AllocError>;
}Allocator: the trait every heap strategy implements.
std::alloc::allocatortype struct Box<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
alloc: A;
}Box<T, A>: single-owner heap allocation.
std::alloc::boxtype struct Rc<T, A = GlobalAlloc> where A: Allocator {
inner: RcInner<T, A>*;
}Rc<T, A>: single-threaded reference counting, with weak references.
std::alloc::rctype struct Arc<T, A = GlobalAlloc> where A: Allocator {
inner: ArcInner<T, A>*;
}Arc<T, A>: atomic reference counting, with weak references.
std::alloc::arctype struct Arena {
head: Chunk*;
current: Chunk*;
chunk_size: u64;
}Arena: bump allocator with bulk release.
std::alloc::arenatype struct Pool {
slot: Layout;
slots_per_block: u64;
free_list: FreeNode*;
blocks: Block*;
}Pool: O(1) allocator for uniformly-sized slots.
std::alloc::poolfunction drop<T>(_v: T) -> voidExplicitly drop a value of type T. This is a no-op for types that do not implement a destructor. The caller is responsible for ensuring that any resources held by _v are properly released if necessary.
mut &this
mut &TypeAn exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.
&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
type struct AllocError {
kind: AllocErrorKind;
layout: Layout;
}type struct GlobalAlloc {}Zero-sized handle to the process-wide allocator. Construct with GlobalAlloc::new(); all instances dispatch through the same underlying backend.
type struct Weak<T, A = GlobalAlloc> {
inner: ArcInner<T, A>*;
}A non-owning reference to an Arc-managed value. Obtain one with Arc::downgrade; recover a strong Arc (if the value still lives) with upgrade. Holding a Weak keeps the header mapped but not the value.