Struct memur::Arena

pub struct Arena { /* fields omitted */ }

Arena is a memory block container that executes drop for your objects when it goes out of scope.

It can not be used between threads. Create a separate Arena for each thread.

You can use this Arena to upload data to memory and receive a pointer to this data. Behind the scenes, the Arena will bump the pointer inside the current block, copy your structure into that location, and return this pointer back. If the Arena runs out of blocks, it will request new blocks from the main Memory.

You should keep a WeakArena reference together with your pointer, and check if it is_alive before every pointer access. As long as you have a copy of WeakArena, the memory won't be deallocated, however if the Arena is dropped and you have uploaded the structure with _auto_drop function, the structure is dropped as well and should not be used.

Arena and WeakArena are not intended to be used directly, instead, you should create wrappers around them for your structures. Inspect List, UStr or N structures for the example code. You will find that these structures do not keep Arena inside, because doing that would produce scenario where the Arena is never dropped when the structures are nested.

When all WeakArena and Arena instances are gone, the memory blocks are returned back to Memory.

Implementations

impl Arena

pub fn new(memory: &Memory) -> Result<Arena, UploadError>

pub unsafe fn upload_auto_drop<T>(
    &self,
    value: T
) -> Result<(*mut T, *const Option<DropItem>), UploadError>

Place item to arena and return a pointer to it, and also add drop function to drop list to drop this item when there are no remaining Arena instances. Result also contains a pointer to drop item that is valid while arena is alive.

pub unsafe fn upload_no_drop<T>(&self, value: T) -> Result<*mut T, UploadError>

Place item to arena and return a pointer to it, without adding a drop function.

pub unsafe fn upload_no_drop_bytes(
    &self,
    len: usize,
    value: impl Iterator<Item = u8>
) -> Result<*mut u8, UploadError>

Place a chunk of bytes to arena and return a pointer to the first byte.

pub unsafe fn alloc_no_drop_items_aligned_uninit<T>(
    &self,
    len: usize,
    offset_between_items: usize
) -> Result<*mut T, UploadError>

Place uninitialized items to arena and return a pointer to the first item. This ensures the alignment of the first item.

pub unsafe fn push_custom_drop_fn(
    &self,
    fun: DropFn,
    data: *const u8
) -> Result<*const Option<DropItem>, UploadError>

Place custom drop function that will be executed on arena drop.

The data pointer should point to a memory location inside the arena.

pub fn to_weak_arena(&self) -> WeakArena

Clone as WeakArena.

Trait Implementations

impl Clone for Arena

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Arena

fn drop(&mut self)

Executes the destructor for this type.