Struct RingBufferProducer 

pub struct RingBufferProducer<T, PW: OptionalWaiter, CW: OptionalWaiter> { /* private fields */ }

Producer side of the ring buffer.

Implementations

impl<T, PW: OptionalWaiter, CW: OptionalWaiter> RingBufferProducer<T, PW, CW>

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

Pushes a single item into the ring buffer.

If there was enough space, returns Ok(()).

If the buffer is full, returns PushError::Full(v). If the receiver had been dropped, returns PushError::Closed(v). The passed-in value is returned so that pushing may be attempted later.

pub fn extend<I: Iterator<Item = T>>( &mut self, it: I, ) -> Result<I, ClosedError<I>>

Pushes a sequence of items into the ring buffer.

Will stop when the iterator runs out of items or the ring buffer runs out of space, whichever comes first. Returns the iterator with the remaining items. It’s recommended to use a FusedIterator.

In the case of the iterator panicing, already-pushed items may not appear to the consumer, and may leak instead.

This can be slightly more efficient than pushing individually, as the atomic operations for updating the counters will not update until all the items are pushed. If T is Copy, consider using RingBufferProducer::push_slice instead.

Returns Err(ClosedError(it)) if the receiver had been dropped, returning the iterator without touching it.

pub fn uninitialized_view( &mut self, ) -> Result<UninitWriteView<'_, T, PW, CW>, ClosedError<()>>

Gets a view into the currently writable portion of this ring buffer.

This returns a wrapper over two slices, which, when concatenated, form the available space in order. The user should write items to the slices in order, then call UninitWriteView::produce to make them available to the consumer.

As opposed to RingBufferProducer::view, this does not do any initialization of the available slots, and so the returned slices have elements of MaybeUninit<T>. Its up to the user to write to the slots via MaybeUninit::write and call UninitWriteView::produce with the correct amount.

This can be used, for example, to read bytes directly to the ring buffer, via [std::io::ReadBuf], without having to use another buffer and paying for the overhead of initializing the values.

pub fn available_len(&self) -> usize

Gets how many items that can be written.

If the consumer side is being used on another thread, the actual amount may increase after this function has returned.

pub fn capacity(&self) -> usize

Returns the maximum number of elements that the buffer can hold.

impl<T: Default, PW: OptionalWaiter, CW: OptionalWaiter> RingBufferProducer<T, PW, CW>

pub fn view(&mut self) -> Result<WriteView<'_, T, PW, CW>, ClosedError<()>>

Gets a view into the currently writable portion of this ring buffer.

This returns a wrapper over two slices, which, when concatenated, form the available space in order. The user should write items to the slices in order, then call UninitWriteView::produce to make them available to the consumer.

As opposed to RingBufferProducer::uninitialized_view, this initializes each element with Default::default, meaning there will be no uninitialized values in the buffer and the interface can be used in safe code.

This can be used, for example, to read bytes directly to the ring buffer, via std::io::Read::read, without having to use another buffer.

pub fn sized_view( &mut self, size: usize, ) -> Result<WriteView<'_, T, PW, CW>, ClosedError<()>>

Gets a view into the currently writable portion of this ring buffer, limited by a size.

Works similar to RingBufferProducer::view, but caps the number of elements in the view to the specified number. This can be used to avoid default-initializing an excessive number of elements.

impl<T: Copy, PW: OptionalWaiter, CW: OptionalWaiter> RingBufferProducer<T, PW, CW>

pub fn push_slice(&mut self, values: &[T]) -> Result<usize, ClosedError<()>>

Pushes a slice of copyable values.

This memcpy’s the slice into the buffer, so it should be more efficient than RingBufferProducer::push or RingBufferProducer::extend.

Returns the amount of items pushed, which may be less than the length of the slice is the buffer fills up.

If the receiver had been dropped, returns Err(ClosedError(())) without touching the values slice.

impl<T, PW, CW: OptionalWaiter> RingBufferProducer<T, PW, CW>

where PW: for<'a> Waiter<'a> + OptionalWaiter,

pub fn wait<'a>(&'a mut self) -> <PW as Waiter<'a>>::Future

Waits for space to become available in the buffer, or for the consumer to be closed.

This method is only available if the buffer was created with a producer waker.

How the wait happens is up to the waiter - it may block, return a future, etc. However, it should return immediately if space is currently available.

pub fn waiter(&mut self) -> &PW

Gets the waiter.

Can be used to alter settings of the waiter, for example, by setting a timeout.

Trait Implementations

impl<T, PW: OptionalWaiter, CW: OptionalWaiter> Drop for RingBufferProducer<T, PW, CW>

fn drop(&mut self)

Executes the destructor for this type.