Struct BlobIdAllocator 

pub struct BlobIdAllocator<'a> { /* private fields */ }

Helper struct implementing the lock-free blob-id allocator over memory.

Represents a thread-safe view into an IOBuffer region of “ID allocator” discipline (ZX_IOB_DISCIPLINE_TYPE_ID_ALLOCATOR), used to map sized data blobs to sequentially-allocated numeric IDs.

Suppose there are N mapped blobs. The memory is laid out as follows, with copies of the blobs growing down and their corresponding bookkeeping indices growing up:

--------------------------------
  next available blob ID (4 bytes)
  blob head offset (4 bytes)
  ----------------------------
  blob 0 size (4 bytes)       } <-- bookkeeping index
  blob 0 offset (4 bytes)     }
  ...
  blob N-1 size (4 bytes)
  blob N-1 offset (4 bytes)
  ----------------------------
  zero-initialized memory      <-- remaining bytes available
  ---------------------------- <-- blob head offset
  blob N-1
  ...
  blob 0
--------------------------------

This struct takes care of the atomic nuance required of accessing and updating such a structure.

Implementations

impl<'a> BlobIdAllocator<'a>

pub fn from_slice(slice: &'a [u8]) -> Self

Constructs a view from a byte slice.

The provided slice must be at least 8-byte-aligned and at least 8 bytes in size.

pub fn init_from_slice(slice: &'a mut [u8], zero_fill: ZeroFill) -> Self

Initializes the backing memory as an ID allocator region with no blobs yet mapped, returning an initialized BlobIdAllocator.

If the region is already known to be zero-filled, zero_fill may be ZeroFill::No.

The provided slice must be at least 8-byte-aligned and at least 8 bytes in size.

pub fn next_id(&self) -> u32

The next ID to be allocated.

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

The remaining number of available bytes in the allocator (including those that might be used for bookkeeping). None is returned in the case of an invalid header (see AllocateError::InvalidHeader for more detail).

pub fn allocate(&self, blob: &[u8]) -> Result<u32, AllocateError>

Attempts to store the provided blob and allocate its ID.

pub fn allocate_with<E>( &self, blob_size: usize, copy: impl FnOnce(&mut [MaybeUninit<u8>]) -> Result<(), E>, ) -> Result<u32, AllocateErrorWith<E>>

A variation of the allocation routine that abstracts the representation of the supplied blob and the manner in which it is copied. This is of particular value to the use of this library in kernel, which requires care in dealing with user-supplied memory.

copy, which performs the copy of blob to a specified destination, is a callable of input signature (dest: &mut [MaybeUninit<u8>]) -> Result<(), E>.

pub fn get_blob(&self, id: u32) -> Result<&'a [u8], BlobError>

Returns the blob corresponding to a given ID.

pub fn iter(&self) -> Iter<'a>

Provides an iterator through all allocated blobs and IDs.

Trait Implementations

impl<'a> Clone for BlobIdAllocator<'a>

fn clone(&self) -> BlobIdAllocator<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for BlobIdAllocator<'a>

impl<'a> Debug for BlobIdAllocator<'a>

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

Formats the value using the given formatter.