Skip to main content

Allocator

zigzag_alloc::alloc::allocator

Trait Allocator 

Source 
pub trait Allocator {
    // Required methods
    unsafe fn alloc(&self, layout: Layout) -> Option<NonNull<u8>>;
    unsafe fn dealloc(&self, ptr: NonNull<u8>, layout: Layout);
}
Expand description

Low-level memory allocator interface.

Inspired by the explicit allocation model of Zig, this trait decouples collections from any concrete or global allocator. Callers retain full control over which memory region is used and when it is released.

§Implementing Allocator

An implementation must uphold the following invariants:

  • A successful call to alloc returns a pointer that is valid for layout.size() bytes and aligned to at least layout.align().
  • The returned memory may contain arbitrary (uninitialized) bytes.
  • The allocated block remains valid until an explicit call to dealloc with the exact same pointer and layout.
  • Calling dealloc with a pointer that was not obtained from the same allocator instance, or with a mismatched layout, is undefined behaviour.

Required Methods§

Source

unsafe fn alloc(&self, layout: Layout) -> Option<NonNull<u8>>

Allocates a block of memory described by layout.

Returns Some(ptr) on success, where ptr is non-null and correctly aligned. Returns None when the allocator cannot satisfy the request (e.g. out of memory, capacity exhausted).

§Safety
  • layout.size() must be greater than zero. Passing a zero-sized layout is undefined behaviour; implementations may panic or return a dangling pointer, but callers must never rely on that behaviour.
  • The caller must eventually call dealloc with the returned pointer and the same layout, unless the allocator uses bulk reclamation (e.g. arena reset).
Source

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

Releases the memory block previously obtained from this allocator.

For allocators that use bulk reclamation (e.g. ArenaAllocator, BumpAllocator) this method is intentionally a no-op; memory is reclaimed collectively via reset() or on drop.

§Safety
  • ptr must have been returned by a prior call to alloc on the same allocator instance.
  • layout must exactly match the layout passed to that alloc call.
  • After dealloc returns, ptr is invalid and must never be dereferenced (prevents use-after-free).
  • Calling dealloc twice with the same pointer is undefined behaviour (double-free).

Implementations on Foreign Types§

Source§

impl<A: Allocator + ?Sized> Allocator for &A

Blanket implementation of Allocator for shared references.

This allows passing &A (or &dyn Allocator) into collections that are generic over A: Allocator, avoiding the need to move ownership of the allocator into every container.

§Example

ⓘ
let sys = SystemAllocator;
let vec: ExVec<u32> = ExVec::new(&sys); // &SystemAllocator implements Allocator
Source§

unsafe fn alloc(&self, layout: Layout) -> Option<NonNull<u8>>

Forwards the allocation request to the underlying allocator.

§Safety

Inherits all safety requirements from A::alloc.

Source§

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

Forwards the deallocation request to the underlying allocator.

§Safety

Inherits all safety requirements from A::dealloc. In particular, ptr must have been allocated by the same underlying allocator instance and layout must match the original allocation.

Implementors§