Struct Arena 

pub struct Arena { /* private fields */ }

Where the target allows it the region begins at a 4 GiB-aligned address and is at most MAX_BLOCK_SIZE bytes, so the low 32 bits of any interior pointer equal its byte offset within the region. Allocation is a pointer bump; deallocation of individual items is a no-op (every chunk is freed at once on drop; or never if using borrowed memory).

Implementations

impl Arena

pub fn new() -> Self

Create a self-allocated arena.

Where address space can be reserved lazily the first chunk is the full MAX_BLOCK_SIZE region, costing no physical memory until written to, so one non-relocating chunk serves arbitrarily large parses. Elsewhere every byte of a chunk is paid for up front, so the arena starts small and adds chunks as it fills.

pub fn with_capacity(size: usize) -> Self

Create a self-allocated arena from a capacity hint.

On targets with virtual memory the hint is rounded up to a reusable size class. Elsewhere it is used exactly. The arena may add chunks when the initial region fills.

Panics

Panics if the backing allocation fails.

pub unsafe fn from_raw_parts(ptr: NonNull<u8>, size: usize) -> Self

Create an arena over caller-owned memory.

Intended for bindings where the original caller owns the memory, e.g. NAPI JS where ArrayBuffer is owned and already allocated.

Safety

ptr must be the base of a live, writable region of at least size bytes that outlives the arena, aligned to BLOCK_ALIGN and no larger than MAX_BLOCK_SIZE, and it must not be handed to another allocator.

pub fn base_ptr(&self) -> NonNull<u8>

The base address of the current usable region.

pub fn transfer_base(&self) -> Option<usize>

Whether every allocation lives in one region starting at Arena::base_ptr, and so whether the low 32 bits of every pointer handed out is its offset into that region.

• Over a reserved region this is Arena::base_ptr, until the arena has to add a chunk: there is then no single region left to be an offset into, and this becomes None.
• Where pointers are 32 bits wide they already are their own offsets, so the base is 0 however many chunks the arena holds: the buffer is the whole address space, which on wasm32 is the linear memory the binding layer already has.
• On a 64 bit target with nothing to reserve - wasm64 under memory64, whose linear memory may exceed 4 GiB - a pointer’s upper half is unconstrained, so its low 32 bits mean nothing and this is always None.

pub fn used_bytes(&self) -> usize

Number of bytes handed out so far.

pub fn capacity(&self) -> usize

Total usable capacity of every chunk in bytes.

pub fn reset(&mut self)

Release every allocation at once by rewinding the bump cursor to the start of the first chunk, freeing any chunk the arena had to add.

Takes &mut self so no allocation can outlive the reset. The first chunk’s memory is retained.

Trait Implementations

impl Allocator for &Arena

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

Attempts to allocate a block of memory.

unsafe fn deallocate(&self, _ptr: NonNull<u8>, _layout: Layout)

Deallocates the memory referenced by ptr.

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

Attempts to extend the memory block.

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

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

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.

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

Attempts to shrink the memory block.

fn by_ref(&self) -> &Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Allocator.

impl Debug for Arena

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Arena

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Arena

fn drop(&mut self)

Executes the destructor for this type.

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.