Struct rtrb::Consumer

pub struct Consumer<T> { /* fields omitted */ }

The consumer side of a RingBuffer.

Can be moved between threads, but references from different threads are not allowed (i.e. it is Send but not Sync).

Can only be created with RingBuffer::split() (together with its counterpart, the Producer).

Examples

use rtrb::RingBuffer;

let (producer, consumer) = RingBuffer::<f32>::new(1000).split();

Implementations

impl<T> Consumer<T>

pub fn pop(&mut self) -> Result<T, PopError>

Attempts to pop an element from the queue.

The element is moved out of the ring buffer and its slot is made available to be filled by the Producer again. If the queue is empty, an error is returned.

Examples

use rtrb::{PopError, RingBuffer};

let (mut p, mut c) = RingBuffer::new(1).split();

assert_eq!(p.push(10), Ok(()));
assert_eq!(c.pop(), Ok(10));
assert_eq!(c.pop(), Err(PopError::Empty));

To obtain an Option<T>, use .ok() on the result.

assert_eq!(p.push(20), Ok(()));
assert_eq!(c.pop().ok(), Some(20));

pub fn peek(&self) -> Result<&T, PeekError>

Attempts to read an element from the queue without removing it.

If the queue is empty, an error is returned.

Examples

use rtrb::{PeekError, RingBuffer};

let (mut p, c) = RingBuffer::new(1).split();

assert_eq!(c.peek(), Err(PeekError::Empty));
assert_eq!(p.push(10), Ok(()));
assert_eq!(c.peek(), Ok(&10));
assert_eq!(c.peek(), Ok(&10));

pub fn read_chunk(&mut self, n: usize) -> Result<ReadChunk<'_, T>, ChunkError>

Returns n slots for reading.

If not enough slots are available, an error (containing the number of available slots) is returned.

The elements can be accessed with ReadChunk::as_slices() or by iterating over (a &mut to) the ReadChunk.

The provided slots are not automatically made available to be written again by the Producer. This has to be explicitly done by calling ReadChunk::commit(), ReadChunk::commit_iterated() or ReadChunk::commit_all(). You can "peek" at the contained values by simply not calling any of the "commit" methods.

Examples

Items are dropped when ReadChunk::commit(), ReadChunk::commit_iterated() or ReadChunk::commit_all() is called (which is only relevant if T implements Drop).

use rtrb::RingBuffer;

// Static variable to count all drop() invocations
static mut DROP_COUNT: i32 = 0;
#[derive(Debug)]
struct Thing;
impl Drop for Thing {
    fn drop(&mut self) { unsafe { DROP_COUNT += 1; } }
}

// Scope to limit lifetime of ring buffer
{
    let (mut p, mut c) = RingBuffer::new(2).split();

    assert!(p.push(Thing).is_ok()); // 1
    assert!(p.push(Thing).is_ok()); // 2
    if let Ok(thing) = c.pop() {
        // "thing" has been *moved* out of the queue but not yet dropped
        assert_eq!(unsafe { DROP_COUNT }, 0);
    } else {
        unreachable!();
    }
    // First Thing has been dropped when "thing" went out of scope:
    assert_eq!(unsafe { DROP_COUNT }, 1);
    assert!(p.push(Thing).is_ok()); // 3

    if let Ok(chunk) = c.read_chunk(2) {
        let (first, second) = chunk.as_slices();
        assert_eq!(first.len(), 1);
        assert_eq!(second.len(), 1);
        assert_eq!(unsafe { DROP_COUNT }, 1);
        chunk.commit(1); // Drops only one of the two Things
        assert_eq!(unsafe { DROP_COUNT }, 2);
    } else {
        unreachable!();
    }
    // The last Thing is still in the queue ...
    assert_eq!(unsafe { DROP_COUNT }, 2);
}
// ... and it is dropped when the ring buffer goes out of scope:
assert_eq!(unsafe { DROP_COUNT }, 3);

See the crate-level documentation for more examples.

pub fn slots(&self) -> usize

Returns the number of slots available for reading.

To check for a single available slot, using Consumer::is_empty() is often quicker (because it might not have to check an atomic variable).

Examples

use rtrb::RingBuffer;

let (p, c) = RingBuffer::<f32>::new(1024).split();

assert_eq!(c.slots(), 0);

pub fn is_empty(&self) -> bool

Returns true if there are no slots available for reading.

Examples

use rtrb::RingBuffer;

let (p, c) = RingBuffer::<f32>::new(1).split();

assert!(c.is_empty());

pub fn buffer(&self) -> &RingBuffer<T>

Returns a read-only reference to the ring buffer.

Trait Implementations

impl<T: Debug> Debug for Consumer<T>

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

Formats the value using the given formatter.

impl<T: Eq> Eq for Consumer<T>

impl<T: PartialEq> PartialEq<Consumer<T>> for Consumer<T>

pub fn eq(&self, other: &Consumer<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Consumer<T>) -> bool

This method tests for !=.

impl Read for Consumer<u8>

pub fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

pub fn read_vectored(
    &mut self,
    bufs: &mut [IoSliceMut<'_>]
) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

pub fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

pub unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

pub fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

pub fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

pub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

pub fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

pub fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

pub fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

pub fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl<T: Send> Send for Consumer<T>

impl<T> StructuralEq for Consumer<T>

impl<T> StructuralPartialEq for Consumer<T>