Struct smoltcp::storage::RingBuffer
source · [−]pub struct RingBuffer<'a, T: 'a> { /* private fields */ }
Expand description
A ring buffer.
This ring buffer implementation provides many ways to interact with it:
- Enqueueing or dequeueing one element from corresponding side of the buffer;
- Enqueueing or dequeueing a slice of elements from corresponding side of the buffer;
- Accessing allocated and unallocated areas directly.
It is also zero-copy; all methods provide references into the buffer’s storage. Note that all references are mutable; it is considered more important to allow in-place processing than to protect from accidental mutation.
This implementation is suitable for both simple uses such as a FIFO queue of UDP packets, and advanced ones such as a TCP reassembly buffer.
Implementations
sourceimpl<'a, T: 'a> RingBuffer<'a, T>
impl<'a, T: 'a> RingBuffer<'a, T>
sourcepub fn new<S>(storage: S) -> RingBuffer<'a, T> where
S: Into<ManagedSlice<'a, T>>,
pub fn new<S>(storage: S) -> RingBuffer<'a, T> where
S: Into<ManagedSlice<'a, T>>,
Create a ring buffer with the given storage.
During creation, every element in storage
is reset.
sourcepub fn reset(&mut self) where
T: Resettable,
pub fn reset(&mut self) where
T: Resettable,
Clear the ring buffer, and reset every element.
sourcepub fn window(&self) -> usize
pub fn window(&self) -> usize
Return the number of elements that can be added to the ring buffer.
sourcepub fn contiguous_window(&self) -> usize
pub fn contiguous_window(&self) -> usize
Return the largest number of elements that can be added to the buffer
without wrapping around (i.e. in a single enqueue_many
call).
sourceimpl<'a, T: 'a> RingBuffer<'a, T>
impl<'a, T: 'a> RingBuffer<'a, T>
This is the “discrete” ring buffer interface: it operates with single elements, and boundary conditions (empty/full) are errors.
sourcepub fn enqueue_one_with<'b, R, F>(&'b mut self, f: F) -> Result<R> where
F: FnOnce(&'b mut T) -> Result<R>,
pub fn enqueue_one_with<'b, R, F>(&'b mut self, f: F) -> Result<R> where
F: FnOnce(&'b mut T) -> Result<R>,
Call f
with a single buffer element, and enqueue the element if f
returns successfully, or return Err(Error::Exhausted)
if the buffer is full.
sourcepub fn enqueue_one(&mut self) -> Result<&mut T>
pub fn enqueue_one(&mut self) -> Result<&mut T>
Enqueue a single element into the buffer, and return a reference to it,
or return Err(Error::Exhausted)
if the buffer is full.
This function is a shortcut for ring_buf.enqueue_one_with(Ok)
.
sourcepub fn dequeue_one_with<'b, R, F>(&'b mut self, f: F) -> Result<R> where
F: FnOnce(&'b mut T) -> Result<R>,
pub fn dequeue_one_with<'b, R, F>(&'b mut self, f: F) -> Result<R> where
F: FnOnce(&'b mut T) -> Result<R>,
Call f
with a single buffer element, and dequeue the element if f
returns successfully, or return Err(Error::Exhausted)
if the buffer is empty.
sourcepub fn dequeue_one(&mut self) -> Result<&mut T>
pub fn dequeue_one(&mut self) -> Result<&mut T>
Dequeue an element from the buffer, and return a reference to it,
or return Err(Error::Exhausted)
if the buffer is empty.
This function is a shortcut for ring_buf.dequeue_one_with(Ok)
.
sourceimpl<'a, T: 'a> RingBuffer<'a, T>
impl<'a, T: 'a> RingBuffer<'a, T>
This is the “continuous” ring buffer interface: it operates with element slices, and boundary conditions (empty/full) simply result in empty slices.
sourcepub fn enqueue_many_with<'b, R, F>(&'b mut self, f: F) -> (usize, R) where
F: FnOnce(&'b mut [T]) -> (usize, R),
pub fn enqueue_many_with<'b, R, F>(&'b mut self, f: F) -> (usize, R) where
F: FnOnce(&'b mut [T]) -> (usize, R),
Call f
with the largest contiguous slice of unallocated buffer elements,
and enqueue the amount of elements returned by f
.
Panics
This function panics if the amount of elements returned by f
is larger
than the size of the slice passed into it.
sourcepub fn enqueue_many(&mut self, size: usize) -> &mut [T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
pub fn enqueue_many(&mut self, size: usize) -> &mut [T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
Enqueue a slice of elements up to the given size into the buffer, and return a reference to them.
This function may return a slice smaller than the given size if the free space in the buffer is not contiguous.
sourcepub fn enqueue_slice(&mut self, data: &[T]) -> usize where
T: Copy,
pub fn enqueue_slice(&mut self, data: &[T]) -> usize where
T: Copy,
Enqueue as many elements from the given slice into the buffer as possible, and return the amount of elements that could fit.
sourcepub fn dequeue_many_with<'b, R, F>(&'b mut self, f: F) -> (usize, R) where
F: FnOnce(&'b mut [T]) -> (usize, R),
pub fn dequeue_many_with<'b, R, F>(&'b mut self, f: F) -> (usize, R) where
F: FnOnce(&'b mut [T]) -> (usize, R),
Call f
with the largest contiguous slice of allocated buffer elements,
and dequeue the amount of elements returned by f
.
Panics
This function panics if the amount of elements returned by f
is larger
than the size of the slice passed into it.
sourcepub fn dequeue_many(&mut self, size: usize) -> &mut [T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
pub fn dequeue_many(&mut self, size: usize) -> &mut [T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
Dequeue a slice of elements up to the given size from the buffer, and return a reference to them.
This function may return a slice smaller than the given size if the allocated space in the buffer is not contiguous.
sourcepub fn dequeue_slice(&mut self, data: &mut [T]) -> usize where
T: Copy,
pub fn dequeue_slice(&mut self, data: &mut [T]) -> usize where
T: Copy,
Dequeue as many elements from the buffer into the given slice as possible, and return the amount of elements that could fit.
sourceimpl<'a, T: 'a> RingBuffer<'a, T>
impl<'a, T: 'a> RingBuffer<'a, T>
This is the “random access” ring buffer interface: it operates with element slices, and allows to access elements of the buffer that are not adjacent to its head or tail.
sourcepub fn get_unallocated(&mut self, offset: usize, size: usize) -> &mut [T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
pub fn get_unallocated(&mut self, offset: usize, size: usize) -> &mut [T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
Return the largest contiguous slice of unallocated buffer elements starting at the given offset past the last allocated element, and up to the given size.
sourcepub fn write_unallocated(&mut self, offset: usize, data: &[T]) -> usize where
T: Copy,
pub fn write_unallocated(&mut self, offset: usize, data: &[T]) -> usize where
T: Copy,
Write as many elements from the given slice into unallocated buffer elements starting at the given offset past the last allocated element, and return the amount written.
sourcepub fn enqueue_unallocated(&mut self, count: usize)
pub fn enqueue_unallocated(&mut self, count: usize)
Enqueue the given number of unallocated buffer elements.
Panics
Panics if the number of elements given exceeds the number of unallocated elements.
sourcepub fn get_allocated(&self, offset: usize, size: usize) -> &[T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
pub fn get_allocated(&self, offset: usize, size: usize) -> &[T]ⓘNotable traits for &'_ mut [u8]impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
Return the largest contiguous slice of allocated buffer elements starting at the given offset past the first allocated element, and up to the given size.
sourcepub fn read_allocated(&mut self, offset: usize, data: &mut [T]) -> usize where
T: Copy,
pub fn read_allocated(&mut self, offset: usize, data: &mut [T]) -> usize where
T: Copy,
Read as many elements from allocated buffer elements into the given slice starting at the given offset past the first allocated element, and return the amount read.
sourcepub fn dequeue_allocated(&mut self, count: usize)
pub fn dequeue_allocated(&mut self, count: usize)
Dequeue the given number of allocated buffer elements.
Panics
Panics if the number of elements given exceeds the number of allocated elements.
Trait Implementations
sourceimpl<'a, T: Debug + 'a> Debug for RingBuffer<'a, T>
impl<'a, T: Debug + 'a> Debug for RingBuffer<'a, T>
sourceimpl<'a, T: 'a> From<ManagedSlice<'a, T>> for RingBuffer<'a, T>
impl<'a, T: 'a> From<ManagedSlice<'a, T>> for RingBuffer<'a, T>
sourcefn from(slice: ManagedSlice<'a, T>) -> RingBuffer<'a, T>
fn from(slice: ManagedSlice<'a, T>) -> RingBuffer<'a, T>
Converts to this type from the input type.
Auto Trait Implementations
impl<'a, T> RefUnwindSafe for RingBuffer<'a, T> where
T: RefUnwindSafe,
impl<'a, T> Send for RingBuffer<'a, T> where
T: Send,
impl<'a, T> Sync for RingBuffer<'a, T> where
T: Sync,
impl<'a, T> Unpin for RingBuffer<'a, T> where
T: Unpin,
impl<'a, T> !UnwindSafe for RingBuffer<'a, T>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more