Trait Deallocator

Source

pub unsafe trait Deallocator {
    // Required method
    unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: NonZeroLayout);
}

Expand description

The deallocation half of an allocator. Every type that issues memory must be able to take it back at drop time.

For arena allocators (BumpArena, parsers), deallocate is a no-op — reclaim happens via reset() (see Allocator::reset).

§Safety

Trait-level invariants implementors must uphold — an implementor of this trait declares the following to all callers:

deallocate accepts any pointer previously returned by the same allocation domain’s Allocator::allocate (or any other method of this trait pair that issued memory — allocate_zeroed, grow, shrink), paired with the same NonZeroLayout used to obtain it. For stateful allocators (Slab, BumpArena, StackAlloc, ExtendableSlab, etc.) the “domain” is the very &self that issued the pointer — pointers from a sibling instance of the same type are UB. For stateless allocators that delegate to a global backing (System, MmapBacked — the OS manages the per-mapping state — any ZST forwarder), the “domain” extends to any instance of the same type, since the OS / global heap is the actual owner. Implementors that are unclear should document explicitly; conservatively, callers should pass the very instance that issued the pointer.
After deallocate returns the pointer is invalid; the caller may not read, write, or compare its address to any new pointer (the integer value may be reused by the allocator). Implementors may additionally poison, quarantine, or return memory to the OS — those are defense-in-depth choices made by hardening wrappers, not requirements of the trait.
Calling deallocate with a pointer that did not originate from this allocator, with a layout that does not match the original allocate call, or with a pointer that has already been deallocated, is undefined behavior.
deallocate may be called from any thread that holds the appropriate &self reference. If the implementor is !Sync the receiver &self itself enforces single-thread access; if Sync the implementor must internally serialize concurrent calls.

Required Methods§

Source

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

Release a previously allocated block.

§Safety

All four of:

ptr must have been returned by a previous call to the same allocation domain’s allocate / allocate_zeroed / grow / shrink (see the trait-level safety doc — for stateful allocators that domain is the same &self; for stateless forwarders to a global backing it is any instance of the same type).
layout must equal the layout supplied to the call that produced ptr — same size and same align. (Wrappers that transparently inflate the layout, e.g. Canary, must inverse-transform before forwarding.)
ptr must not have been previously deallocated. Double-free is UB.
After the call, the caller must not read, write, or compare against new pointers the value of ptr.