Struct SpscRing 

pub struct SpscRing<T, const N: usize> { /* private fields */ }

A fixed-capacity SPSC ring buffer that holds items of type T.

The const generic N sets the number of backing slots. One slot is kept as a sentinel, so the buffer holds at most N - 1 items concurrently.

Example

use fin_stream::ring::SpscRing;

let ring: SpscRing<u64, 8> = SpscRing::new();
ring.push(42).unwrap();
assert_eq!(ring.pop().unwrap(), 42);

Implementations

impl<T, const N: usize> SpscRing<T, N>

pub fn new() -> Self

Construct an empty ring buffer.

pub fn is_empty(&self) -> bool

Returns true if the buffer contains no items.

pub fn is_full(&self) -> bool

Returns true if the buffer has no free slots.

pub fn len(&self) -> usize

Number of items currently in the buffer.

pub fn capacity(&self) -> usize

Maximum number of items the buffer can hold.

pub fn push(&self, item: T) -> Result<(), StreamError>

Push an item into the buffer.

Returns Err(StreamError::RingBufferFull) if the buffer is full. Never panics.

Complexity: O(1), allocation-free.

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

Pop an item from the buffer.

Returns Err(StreamError::RingBufferEmpty) if the buffer is empty. Never panics.

Complexity: O(1), allocation-free.

pub fn try_push_or_drop(&self, item: T) -> bool

Push an item, silently dropping it and returning false if the buffer is full.

Unlike push, this never returns an error — it accepts data loss under backpressure. Suitable for non-critical metrics or telemetry where occasional drops are preferable to blocking or erroring.

Returns true if the item was enqueued, false if it was dropped.

Complexity: O(1), allocation-free.

pub fn peek_clone(&self) -> Option<T>

where T: Clone,

Clone the next item from the ring without removing it.

Returns None if the ring is empty. The item remains available for a subsequent pop call.

Complexity: O(1).

pub fn peek_all(&self) -> Vec<T>

where T: Clone,

Clone all items currently in the ring into a Vec, in FIFO order, without consuming them.

Only safe to call when no producer/consumer pair is active (i.e., before calling split()). The ring is left unchanged.

Complexity: O(n).

pub fn peek_newest(&self) -> Option<T>

where T: Copy,

Returns a copy of the most recently pushed item without consuming it, or None if the ring is empty.

“Newest” is the item at tail - 1 — the last item that was pushed. Unlike pop (which removes from the head), this leaves the ring unchanged.

pub fn peek_oldest(&self) -> Option<T>

where T: Copy,

Peek at the oldest item in the ring (the one that would be returned next by pop) without removing it.

Returns None when the ring is empty.

pub fn fill_ratio(&self) -> f64

Current fill level as a fraction of capacity: len / capacity.

Returns 0.0 when empty and 1.0 when full.

pub fn has_capacity(&self, n: usize) -> bool

Returns true if there is enough free space to push n more items.

Equivalent to self.len() + n <= self.capacity().

pub fn utilization_pct(&self) -> f64

Fill level as a percentage of capacity: fill_ratio() * 100.0.

Returns 0.0 when empty and 100.0 when full.

pub fn remaining_capacity(&self) -> usize

Number of additional items that can be pushed before the buffer is full.

pub fn is_nearly_full(&self, threshold: f64) -> bool

Returns true if the fill ratio exceeds threshold (a value in [0.0, 1.0]).

For example, is_nearly_full(0.9) returns true when the buffer is ≥ 90% full.

pub fn first(&self) -> Option<T>

where T: Copy,

Returns a copy of the oldest item (front) without removing it.

Returns None if the buffer is empty. Only valid before calling split().

pub fn peek_front(&self) -> Option<&T>

Returns a reference to the oldest item (front) without removing it.

Returns None if the buffer is empty. Only valid before calling split().

pub fn peek_back(&self) -> Option<&T>

Returns a reference to the newest item (back) without removing it.

Returns None if the buffer is empty. Only valid before calling split().

pub fn drain(&self) -> Vec<T>

Drain all items currently in the ring into a Vec, in FIFO order.

Only safe to call when no producer/consumer pair is active (i.e., before calling split()).

Complexity: O(n).

pub fn drain_into(&self, buf: &mut Vec<T>)

Drain all items from the ring into buf in FIFO order, appending to any existing contents of buf.

Only safe to call when no producer/consumer pair is active (i.e., before calling split()). Useful for draining into a pre-allocated buffer to avoid allocation.

Complexity: O(n).

pub fn to_vec_cloned(&self) -> Vec<T>

where T: Clone,

Returns a snapshot of all items in FIFO order without removing them.

Only valid before calling split(). Requires T: Clone.

Complexity: O(n).

pub fn to_vec_sorted(&self) -> Vec<T>

where T: Clone + Ord,

Returns a sorted Vec of all ring elements, cloned.

The ring itself is not modified. An empty ring returns an empty vec.

Complexity: O(n log n).

pub fn min_cloned(&self) -> Option<T>

where T: Clone + Ord,

Returns the minimum item in the ring by cloning, without removing any items.

Returns None if the ring is empty. Only valid before calling split().

Complexity: O(n).

pub fn max_cloned(&self) -> Option<T>

where T: Clone + Ord,

Returns the maximum item in the ring by cloning, without removing any items.

Returns None if the ring is empty. Only valid before calling split().

Complexity: O(n).

pub fn count_if<F>(&self, predicate: F) -> usize

where F: Fn(&T) -> bool,

Count items in the ring that satisfy predicate, without removing them.

Only valid before calling split(). Requires T to be readable via shared ref.

Complexity: O(n).

pub fn peek_nth(&self, n: usize) -> Option<T>

where T: Clone,

Returns the nth oldest element in the ring (0 = oldest), cloned.

Returns None if n is out of bounds.

Complexity: O(1).

pub fn min_cloned_by<F, K>(&self, key: F) -> Option<T>

where T: Clone, F: Fn(&T) -> K, K: Ord,

Returns the element for which key(element) is minimum, cloned.

Returns None if the ring is empty.

Complexity: O(n).

pub fn max_cloned_by<F, K>(&self, key: F) -> Option<T>

where T: Clone, F: Fn(&T) -> K, K: Ord,

Returns the element for which key(element) is maximum, cloned.

Returns None if the ring is empty.

Complexity: O(n).

pub fn contains_cloned(&self, value: &T) -> bool

where T: Clone + PartialEq,

Returns true if the ring contains an element equal to value.

Complexity: O(n).

pub fn average_cloned(&self) -> Option<f64>

where T: Clone + Into<f64>,

Arithmetic mean of all elements in the ring, as f64.

Returns None if the ring is empty.

Complexity: O(n).

pub fn sum_cloned(&self) -> T

where T: Clone + Sum + Default,

Sum of all elements currently in the ring, cloned out of initialized slots.

Returns T::default() (typically 0) when the ring is empty.

Complexity: O(n).

pub fn split(self) -> (SpscProducer<T, N>, SpscConsumer<T, N>)

Split the ring into a thread-safe producer/consumer pair.

The original SpscRing is consumed. Both halves hold an Arc to the shared backing store.

Example

use fin_stream::ring::SpscRing;
use std::thread;

let ring: SpscRing<u64, 64> = SpscRing::new();
let (prod, cons) = ring.split();

let handle = thread::spawn(move || {
    prod.push(99).unwrap();
});
handle.join().unwrap();
assert_eq!(cons.pop().unwrap(), 99u64);

Trait Implementations

impl<T, const N: usize> Default for SpscRing<T, N>

fn default() -> Self

Returns the “default value” for a type.

impl<T, const N: usize> Drop for SpscRing<T, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send, const N: usize> Send for SpscRing<T, N>