Struct rtrb::Producer

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

The producer 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 Consumer).

When the Producer is dropped, Consumer::is_abandoned() will return true. This can be used as a crude way to communicate to the receiving thread that no more data will be produced. When the Producer is dropped after the Consumer has already been dropped, RingBuffer::drop() will be called, freeing the allocated memory.

Examples

use rtrb::RingBuffer;

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

Implementations

impl<T> Producer<T>

pub fn push(&mut self, value: T) -> Result<(), PushError<T>>

Attempts to push an element into the queue.

The element is moved into the ring buffer and its slot is made available to be read by the Consumer. If the queue is full, the element is returned back as an error.

Examples

use rtrb::{RingBuffer, PushError};

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

assert_eq!(p.push(10), Ok(()));
assert_eq!(p.push(20), Err(PushError::Full(20)));

pub fn write_chunk(&mut self, n: usize) -> Result<WriteChunk<'_, T>, ChunkError> where
    T: Copy + Default, 

Returns n slots (initially containing their Default value) for writing.

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

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

The provided slots are not automatically made available to be read by the Consumer. This has to be explicitly done by calling WriteChunk::commit(), WriteChunk::commit_iterated() or WriteChunk::commit_all().

The type parameter T has a trait bound of Copy, which makes sure that no destructors are called at any time (because it implies !Drop).

For an unsafe alternative that has no restrictions on T, see Producer::write_chunk_uninit().

Examples

See the crate-level documentation for examples.

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

Returns n (uninitialized) slots for writing.

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

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

The provided slots are not automatically made available to be read by the Consumer. This has to be explicitly done by calling WriteChunkUninit::commit(), WriteChunkUninit::commit_iterated() or WriteChunkUninit::commit_all().

Safety

This function itself is safe, but accessing the returned slots might not be, as well as invoking some methods of WriteChunkUninit.

For a safe alternative that provides Default-initialized slots, see Producer::write_chunk().

pub fn slots(&self) -> usize

Returns the number of slots available for writing.

Since items can be concurrently consumed on another thread, the actual number of available slots may increase at any time (up to the RingBuffer::capacity()).

To check for a single available slot, using Producer::is_full() 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!(p.slots(), 1024);

pub fn is_full(&self) -> bool

Returns true if there are currently no slots available for writing.

Examples

use rtrb::RingBuffer;

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

assert!(!p.is_full());

Since items can be concurrently consumed on another thread, the ring buffer might not be full for long:

if p.is_full() {
    // The buffer might be full, but it might as well not be
    // if an item was just consumed on another thread.
}

However, if it’s not full, another thread cannot change that:

if !p.is_full() {
    // At least one slot is guaranteed to be available for writing.
}

pub fn is_abandoned(&self) -> bool

Returns true if the corresponding Consumer has been destroyed.

Examples

use rtrb::RingBuffer;

let (mut p, c) = RingBuffer::new(7).split();
assert!(!p.is_abandoned());
assert_eq!(p.push(10), Ok(()));
drop(c);
// The items that are still in the ring buffer are not accessible anymore.
assert!(p.is_abandoned());
// Even though it's futile, items can still be written:
assert_eq!(p.push(11), Ok(()));

Since the consumer can be concurrently dropped on another thread, the producer might become abandoned at any time:

if !p.is_abandoned() {
    // Right now, the consumer might still be alive, but it might as well not be
    // if another thread has just dropped it.
}

However, if it already is abandoned, it will stay that way:

if p.is_abandoned() {
    // The consumer does definitely not exist anymore.
}

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

Returns a read-only reference to the ring buffer.

Trait Implementations

impl<T: Debug> Debug for Producer<T>

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

Formats the value using the given formatter.

impl Write for Producer<u8>

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

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

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

Creates a “by reference” adaptor for this instance of Write.

impl<T: Send> Send for Producer<T>