Struct BlockRef 

pub struct BlockRef { /* private fields */ }

A reference to a block of memory capacity owned by a memory provider and leased to user code.

While a memory provider only leases each block to one caller at a time, this caller may further share and subdivide the block between multiple co-owners. These co-owners will coordinate the read/write permissions over different slices of the block via their own logic, with the BlockRef only used to represent the block as a whole, each co-owner having a cloned BlockRef to the same block.

Implementation design

Each memory provider implements its own accounting logic for tracking the memory blocks it provides. This takes the form of a “manual” dynamic dispatch implementation via a function table and data pointer passed to new().

You can think of BlockRef as an Arc<RealBlock>, except we are intentionally obscuring the RealBlock from the API surface to allow all code upstream of BlockRef to be ignorant of the real type of the block.

The assumption is that an efficient memory provider will allocate its data objects in a pool, so if the BlockRef itself is held on the stack, there are no heap allocations necessary to operate on memory blocks. This would be infeasible to achieve with trait objects, which are unsized and have significant limitations on how they can be used. This is why we use the manual dynamic dispatch mechanism instead of using Rust’s trait system.

Implementations

impl BlockRef

pub const unsafe fn new<T: BlockRefDynamic>( state: NonNull<T::State>, vtable: &'static BlockRefVTable<T>, ) -> Self

Creates a new block reference using the provided dynamic implementation state and matching function table.

Safety

state must remain valid for reads and writes until BlockRefDynamic::drop is called via vtable.

pub fn meta(&self) -> Option<&dyn Any>

Memory provider specific metadata describing the block.

Trait Implementations

impl Clone for BlockRef

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BlockRef

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

Formats the value using the given formatter.

impl Drop for BlockRef

fn drop(&mut self)

Executes the destructor for this type.

impl Send for BlockRef

impl Sync for BlockRef