Struct Ring

pub struct Ring { /* private fields */ }

A low-level atomic ring-buffer building block.

This type implements logic for managing the two non-overlapping regions of a ring buffer mapped to linear storage. This is useful for implementing safe, higher-level queues such as nonblocking and asyncio.

Ring models two “regions”, named the left and right region, of a conceptual fixed-length ring array. Each region can advance itself, moving data at the start of the region to the end of the other region. This allows data in each region to be read and written independently, then fed to the other region without synchronization.

When a region is mapped to a linear array, which has a start and end index, it might end up in two “chunks” where it overlaps the edge of the array. Ring provides access to the indices of the first chunks in the left and right region, as well as logic to advance each region. It does not contain the buffer itself.

Implementations

impl Ring

pub fn new(capacity: usize) -> Self

Creates a ring with a specific capacity.

The ring starts with an empty left region and a right range from index 0 to the capacity.

pub fn capacity(&self) -> usize

Gets the capacity of the ring.

pub fn display( &self, width: usize, left_char: char, right_char: char, ) -> Display<'_>

Returns an object that implements Display with specific formatting. This is useful for debugging the stage of the ring.

Example

use mini_io_queue::Ring;

let ring = Ring::new(16);
ring.advance_right(4);

let s = format!("{}", ring.display(16, 'L', 'R'));
assert_eq!(s, "LLLLRRRRRRRRRRRR");

pub fn left_ranges(&self) -> (Range<usize>, Range<usize>)

Gets the range of indices in both chunks of the left region. Both or one range can be empty. The ranges will never overlap.

The function guarantees that the start index of both ranges will stay the same across calls, and the end index will only increase, until the range is invalidated.

This function also guarantees that the returned ranges will never overlap with a range returned by right_ranges, as long as the ranges are not invalidated.

The ranges are invalidated by advancing the region by calling advance_left or advance_left_unchecked. Any ranges read before advancing are effectively meaningless after advancing. Invalidated ranges must not be used to slice an underlying array, or you may end up with overlapping left and right slices.

pub fn left_len(&self) -> usize

Gets the total length of the left region. This will always match the combined lengths of the slices returned by left_ranges. This will always be less than or equal to the ring’s capacity.

pub fn advance_left(&self, len: usize)

Advances the left region, conceptually moving len elements at the start of the left region to the end of the right region and shrinking the left region as a result.

Panics

Panics if len is larger than the current size of the left region.

pub unsafe fn advance_left_unchecked(&self, len: usize)

Advances the left region, conceptually moving len elements at the start of the left region to the end of the right region and shrinking the left region as a result.

Safety

len must be less than or equal to the length of the left region returned by left_len.

pub fn right_ranges(&self) -> (Range<usize>, Range<usize>)

Gets the range of indices in the both chunks of the right region. Both or one range can be empty. The ranges will never overlap.

The function guarantees that the start index of both ranges will stay the same across calls, and the end index will only increase, until the range is invalidated.

This function also guarantees that the returned rangse will never overlap with a range returned by left_ranges, as long as the ranges are not invalidated.

The ranges are invalidated by advancing the region by calling advance_right or advance_right_unchecked. Any ranges read before advancing are effectively meaningless after advancing. Invalidated ranges must not be used to slice an underlying array, or you may end up with overlapping left and right slices.

pub fn right_len(&self) -> usize

Gets the total length of the right region. This will always match the combined lengths of the slices returned by right_ranges. This will always be less than or equal to the ring’s capacity.

pub fn advance_right(&self, len: usize)

Advances the right region, conceptually moving len elements at the start of the right region to the end of the left region and shrinking the right region as a result.

Panics

Panics if len is larger than the current size of the right region.

pub unsafe fn advance_right_unchecked(&self, len: usize)

Advances the right region, conceptually moving len elements at the start of the right region to the end of the left region and shrinking the right region as a result.

Safety

len must be less than or equal to the length of the left region returned by right_len.

Trait Implementations

impl Debug for Ring

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

Formats the value using the given formatter.

impl Default for Ring

fn default() -> Ring

Returns the “default value” for a type.