Struct Buffer 

pub struct Buffer<A: Allocator + Default = DefaultAllocator> { /* private fields */ }

A transactional, single-producer, single-consumer ring buffer.

The caller is responsible for ensuring that there is only one reader and one writer; no internal synchronization is provided to enforce this constraint.

Backing storage is allocated dynamically during the init method. The requested size must be a power of two for correct functionality.

Implementations

impl<A: Allocator + Default> Buffer<A>

pub fn try_new_in(size: u32, allocator: A) -> Result<Self, Status>

Constructs a new Buffer with a dynamically allocated backing storage of the given size, using the given allocator.

pub fn is_valid(&self) -> bool

Returns true if the buffer has valid backing storage (non-null and valid power-of-two size).

pub const fn size(&self) -> u32

Returns the size of the backing storage.

pub fn reserve(&mut self, size: u32) -> Result<Reservation<'_>, Status>

Reserves a block of the given size in the buffer.

Any data written into this block will not be visible to readers until commit is called on the returned Reservation.

pub unsafe fn reserve_shared( &self, size: u32, ) -> Result<Reservation<'_>, Status>

Reserves a block of the given size in the buffer via a shared reference.

Any data written into this block will not be visible to readers until commit is called on the returned Reservation.

Safety

The caller must ensure that there is at most one active producer reservation on self at a time (no concurrent calls to reserve or reserve_shared, and no live Reservation overlapping with another call to reserve or reserve_shared).

pub fn read<F>(&self, copy_fn: F, len: u32) -> Result<u32, Status>

where F: FnMut(u32, &[u8]) -> Result<(), Status>,

Copies len bytes out of the buffer using the provided copy_fn.

The copy function has the signature copy_fn(offset: u32, src: &[u8]) -> Result<(), Status> and may be invoked multiple times.

Returns the number of bytes read on success. If copy_fn returns an error, that error is propagated.

Importantly, even if an error is returned, copy_fn might have already processed a partial amount of data (between 0 and len bytes). However, these partially processed bytes are considered not read. Consequently, the internal read pointer of the ring buffer will not be advanced for these unread bytes, meaning that these same bytes will remain available for reading in subsequent calls to read.

pub fn drain(&self) -> Result<(), Status>

Empties the contents of the buffer.

This is logically a read operation, so a read and drain cannot be called concurrently. Additionally, the behavior of this method is non-deterministic if a write is in-progress.

impl Buffer<DefaultAllocator>

pub fn try_new(size: u32) -> Result<Self, Status>

Constructs a new Buffer with a dynamically allocated backing storage of the given size, using the default allocator.

impl Buffer<NoOpAllocator>

pub unsafe fn from_raw_parts(storage: *mut u8, size: usize) -> Self

Constructs a Buffer from raw pointers using a no-op allocator.

The returned buffer does not own the memory and will not deallocate it when dropped.

Safety

• storage must be non-null and point to a valid, initialized slice of bytes whose length is a power of two and does not exceed MAX_STORAGE_SIZE.

pub const fn empty() -> Self

Constructs an empty Buffer with null storage and zero size (for testing).

pub fn take_raw_parts(&mut self) -> (*mut u8, usize)

Resets the buffer to empty and returns the raw storage pointer and size.

Trait Implementations

impl<A: Allocator + Default> Drop for Buffer<A>

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.