Struct bbqueue::Producer

pub struct Producer<'a, const N: usize> { /* fields omitted */ }

Producer is the primary interface for pushing data into a BBBuffer. There are various methods for obtaining a grant to write to the buffer, with different potential tradeoffs. As all grants are required to be a contiguous range of data, different strategies are sometimes useful when making the decision between maximizing usage of the buffer, and ensuring a given grant is successful.

As a short summary of currently possible grants:

• grant_exact(N)
  • User will receive a grant sz == N (or receive an error)
  • This may cause a wraparound if a grant of size N is not available at the end of the ring.
  • If this grant caused a wraparound, the bytes that were “skipped” at the end of the ring will not be available until the reader reaches them, regardless of whether the grant commited any data or not.
  • Maximum possible waste due to skipping: N - 1 bytes
• grant_max_remaining(N)
  • User will receive a grant 0 < sz <= N (or receive an error)
  • This will only cause a wrap to the beginning of the ring if exactly zero bytes are available at the end of the ring.
  • Maximum possible waste due to skipping: 0 bytes

See this github issue for a discussion of grant methods that could be added in the future.

Implementations

impl<'a, const N: usize> Producer<'a, N>

pub fn grant_exact(&mut self, sz: usize) -> Result<GrantW<'a, N>>

Request a writable, contiguous section of memory of exactly sz bytes. If the buffer size requested is not available, an error will be returned.

This method may cause the buffer to wrap around early if the requested space is not available at the end of the buffer, but is available at the beginning

use bbqueue::BBBuffer;

// Create and split a new buffer of 6 elements
let buffer: BBBuffer<6> = BBBuffer::new();
let (mut prod, cons) = buffer.try_split().unwrap();

// Successfully obtain and commit a grant of four bytes
let mut grant = prod.grant_exact(4).unwrap();
assert_eq!(grant.buf().len(), 4);
grant.commit(4);

// Try to obtain a grant of three bytes
assert!(prod.grant_exact(3).is_err());

pub fn grant_max_remaining(&mut self, sz: usize) -> Result<GrantW<'a, N>>

Request a writable, contiguous section of memory of up to sz bytes. If a buffer of size sz is not available without wrapping, but some space (0 < available < sz) is available without wrapping, then a grant will be given for the remaining size at the end of the buffer. If no space is available for writing, an error will be returned.

use bbqueue::BBBuffer;

// Create and split a new buffer of 6 elements
let buffer: BBBuffer<6> = BBBuffer::new();
let (mut prod, mut cons) = buffer.try_split().unwrap();

// Successfully obtain and commit a grant of four bytes
let mut grant = prod.grant_max_remaining(4).unwrap();
assert_eq!(grant.buf().len(), 4);
grant.commit(4);

// Release the four initial commited bytes
let mut grant = cons.read().unwrap();
assert_eq!(grant.buf().len(), 4);
grant.release(4);

// Try to obtain a grant of three bytes, get two bytes
let mut grant = prod.grant_max_remaining(3).unwrap();
assert_eq!(grant.buf().len(), 2);
grant.commit(2);

Trait Implementations

impl<'a, const N: usize> Send for Producer<'a, N>