pub struct Heap { /* private fields */ }Expand description
A first-class heap (plan §5.14): Drop runs mi_heap_delete semantics
(blocks migrate to the thread’s backing heap and stay valid) unless built
with Heap::new_destroyable, where Drop releases every block at once.
The destroyable form inherits C’s contract for the raw methods below:
callers must not touch its blocks after drop. With the allocator-api
feature that is unrepresentable in safe code: a collection made with
Vec::new_in(&heap) borrows the heap and cannot outlive it.
Implementations§
Source§impl Heap
impl Heap
Sourcepub fn new() -> Heap
pub fn new() -> Heap
New heap; dropped ⇒ blocks migrate to the backing heap.
§Panics
When the OS refuses the heap’s backing mapping (memory exhaustion) — a defined panic, matching std’s convention for infallible constructors, rather than a null pointer carried into later use.
Sourcepub fn new_destroyable() -> Heap
pub fn new_destroyable() -> Heap
Sourcepub fn alloc(&self, layout: Layout) -> Option<NonNull<u8>>
pub fn alloc(&self, layout: Layout) -> Option<NonNull<u8>>
Allocate layout, borrowing the heap (so the block cannot outlive it).
#[inline], like the GlobalAlloc methods below and for their reason:
the fast path is a pop from the heap’s direct table, and it belongs in
the caller. Out of line through heap_malloc it cost 28 instructions
and a call on every allocation, against the global handle’s inline
pop, which is what put a Vec in a heap 6.6 % behind one on the global
allocator (docs/opps.md, “The Allocator route”).
Sourcepub unsafe fn dealloc(&self, p: NonNull<u8>)
pub unsafe fn dealloc(&self, p: NonNull<u8>)
Free a block previously allocated from this heap.
§Safety
p came from this heap’s alloc methods and is freed exactly once.
Sourcepub fn contains(&self, p: NonNull<u8>) -> bool
pub fn contains(&self, p: NonNull<u8>) -> bool
Whether p points into memory this heap owns (mi_heap_contains_block).
A diagnostic, and not a fast one: it walks the heap’s segments. It answers by segment, so it is true of any address inside one of them, allocated or not, and false of a block of another heap or of the global allocator. Any address may be asked about; nothing is read through it.
Trait Implementations§
Source§impl Allocator for Heap
impl Allocator for Heap
Source§fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
Source§fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>
allocate, but also ensures that the returned memory is zero-initialized. Read moreSource§unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)
unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)
ptr. Read more