Skip to main content

Heap

Struct Heap 

Source
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

Source

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.

Source

pub fn new_destroyable() -> Heap

New heap; dropped ⇒ every allocation is released wholesale (arena-style teardown).

§Panics

As Heap::new, on memory exhaustion.

Source

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

Source

pub fn alloc_zeroed(&self, layout: Layout) -> Option<NonNull<u8>>

Zeroed variant of alloc.

Source

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.

Source

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.

Source

pub fn collect(&self)

Drain cross-thread frees and retire empty pages.

Trait Implementations§

Source§

impl Allocator for Heap

Source§

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

Attempts to allocate a block of memory. Read more
Source§

fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

Behaves like allocate, but also ensures that the returned memory is zero-initialized. Read more
Source§

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

Deallocates the memory referenced by ptr. Read more
Source§

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Attempts to extend the memory block. Read more
Source§

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Behaves like grow, but also ensures that the new contents are set to zero before being returned. Read more
Source§

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Attempts to shrink the memory block. Read more
Source§

impl Default for Heap

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Drop for Heap

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

§

impl !RefUnwindSafe for Heap

§

impl !Send for Heap

§

impl !Sync for Heap

§

impl !UnwindSafe for Heap

§

impl Forget for Heap

§

impl Freeze for Heap

§

impl Move for Heap

§

impl Unpin for Heap

§

impl UnsafeUnpin for Heap

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.