Struct TRBuffer

pub struct TRBuffer<T> { /* private fields */ }

A TRBuffer is similar to a circular buffer, but data is inserted in three revolving regions of the buffer space. This allows reads to return contiguous blocks of memory, even if they span a region that would normally include a wrap-around in a circular buffer. It’s especially useful for APIs requiring blocks of contiguous memory, eliminating the need to copy data into an interim buffer before use.

Example

use triskell::TRBuffer;

// Creates a TRBuffer of u8 and allocates 8 elements.
let mut buffer: TRBuffer<u8> = TRBuffer::with_capacity(8);
{
  // Reserves 4 slots at the back for insert
  let reserved = buffer.reserve_back(4).unwrap();
  reserved[0] = 2;
  reserved[1] = 12;
  reserved[2] = 34;
  reserved[3] = 7;
}
// Stores the values into an available region
buffer.commit(4);
{
  // Gets the front data stored in the region as a contiguous block
  let block = buffer.read_front().unwrap();
  assert_eq!(block[0], 2);
  assert_eq!(block[1], 12);
  assert_eq!(block[2], 34);
  assert_eq!(block[3], 7);
}
// Release the first two front elements of the block
buffer.free_front(2);
{
  let block = buffer.read_front().unwrap();
  assert_eq!(block[0], 34);
  assert_eq!(block[1], 7);
}

Implementations

impl<T> TRBuffer<T>

pub fn new() -> Self

Construct a new empty TRBuffer.

pub fn with_capacity(len: usize) -> Self

Construct a new empty TRBuffer with at least the specified capacity.

The TRBuffer will be able to hold at least capacity elements without reallocating.

pub fn capacity(&self) -> usize

Return the total number of elements the TRBuffer can hold without reallocating.

pub fn set_allocation_strategy( &mut self, allocation_strategy: AllocationStrategy, )

Define the allocation strategy.

pub fn is_empty(&self) -> bool

Returns true if the TRBuffer contains no elements.

pub fn len(&self) -> usize

Returns the number of elements in the TRBuffer.

pub fn clear(&mut self)

Clears all regions and reservations.

pub fn reserve_front(&mut self, len: usize) -> Result<&mut [T], TriskellError>

Reserves len bytes to be prepended and return a mutable slice of T.

If there is not enough space, reallocates the buffer.

pub fn reserve_back(&mut self, len: usize) -> Result<&mut [T], TriskellError>

Reserves len bytes to be appended and return a mutable slice of T.

If there is not enough space, reallocates the buffer.

pub fn commit(&mut self, len: usize)

Commits the data in the reservation, allowing it to be read later

pub fn read_front(&self) -> Option<&[T]>

Retrieves available (committed) data as a contiguous block (FIFO).

Returns None if there is no data available Must called free_front() to free data.

pub fn read_front_mut(&mut self) -> Option<&mut [T]>

pub fn read_front_indexes(&self) -> Option<(usize, usize)>

pub fn read_back(&self) -> Option<&[T]>

Retrieves available (committed) data as a contiguous block (LIFO).

Returns None if there is no data available Must called free_back() to free data.

pub fn read_back_mut(&mut self) -> Option<&mut [T]>

pub fn read_back_indexes(&self) -> Option<(usize, usize)>

pub fn get(&self, start: usize, end: usize) -> &[T]

pub fn get_mut(&mut self, start: usize, end: usize) -> &mut [T]

pub fn free_front(&mut self, len: usize)

Remove len bytes at the beginning of the buffer.

The next time read() is called, it will not include these elements.

pub fn free_back(&mut self, len: usize)

Remove len bytes at the end of the buffer.

The next time read() is called, it will not include these elements.

Trait Implementations

impl<T: Debug> Debug for TRBuffer<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for TRBuffer<T>

fn default() -> TRBuffer<T>

Returns the “default value” for a type.