use std::sync::atomic::AtomicU64;
use std::sync::atomic::Ordering;
use std::sync::Mutex;
use tokio::sync::Notify;
#[allow(dead_code)]
pub(crate) struct RxRing {
capacity: usize,
inner: Mutex<Inner>,
notify: Notify,
bytes_wrapped_total: AtomicU64,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[allow(dead_code)]
pub(crate) struct RingSlice {
pub bytes: Vec<u8>,
pub from_offset: u64,
pub next_offset: u64,
pub bytes_lost: u64,
}
#[allow(dead_code)]
struct Inner {
buf: Vec<u8>,
start_offset: u64,
end_offset: u64,
}
#[allow(dead_code)]
impl RxRing {
pub fn new(capacity: usize) -> Self {
assert!(capacity > 0, "RxRing capacity must be > 0");
Self {
capacity,
inner: Mutex::new(Inner {
buf: vec![0u8; capacity],
start_offset: 0,
end_offset: 0,
}),
notify: Notify::new(),
bytes_wrapped_total: AtomicU64::new(0),
}
}
pub fn capacity(&self) -> usize {
self.capacity
}
pub fn start_offset(&self) -> u64 {
self.inner.lock().expect("ring mutex poisoned").start_offset
}
pub fn end_offset(&self) -> u64 {
self.inner.lock().expect("ring mutex poisoned").end_offset
}
pub fn bytes_wrapped_total(&self) -> u64 {
self.bytes_wrapped_total.load(Ordering::Relaxed)
}
}
#[allow(dead_code)]
impl RxRing {
pub fn append(&self, bytes: &[u8]) {
if bytes.is_empty() {
return;
}
let n = bytes.len() as u64;
let cap = self.capacity as u64;
let mut inner = self.inner.lock().expect("ring mutex poisoned");
let old_end = inner.end_offset;
let new_end = old_end + n;
let new_start = std::cmp::max(inner.start_offset, new_end.saturating_sub(cap));
let lost = new_start.saturating_sub(inner.start_offset);
if lost > 0 {
self.bytes_wrapped_total.fetch_add(lost, Ordering::Relaxed);
}
let survive_start_logical = std::cmp::max(new_start, old_end);
let survive_len = (new_end - survive_start_logical) as usize;
let input_offset = (survive_start_logical - old_end) as usize;
let src = &bytes[input_offset..input_offset + survive_len];
let phys_start = (survive_start_logical % cap) as usize;
write_ring(&mut inner.buf, phys_start, src);
inner.start_offset = new_start;
inner.end_offset = new_end;
drop(inner);
self.notify.notify_waiters();
}
}
#[allow(dead_code)]
impl RxRing {
pub fn read_from(&self, cursor: u64, max: usize) -> RingSlice {
let inner = self.inner.lock().expect("ring mutex poisoned");
let start = inner.start_offset;
let end = inner.end_offset;
let bytes_lost = start.saturating_sub(cursor);
let from_offset = if cursor < start {
start
} else if cursor > end {
return RingSlice {
bytes: Vec::new(),
from_offset: end,
next_offset: end,
bytes_lost,
};
} else {
cursor
};
if from_offset >= end || max == 0 {
return RingSlice {
bytes: Vec::new(),
from_offset,
next_offset: from_offset,
bytes_lost,
};
}
let available = (end - from_offset) as usize;
let take = max.min(available);
let cap = self.capacity as u64;
let phys_start = (from_offset % cap) as usize;
let bytes = read_ring(&inner.buf, phys_start, take);
RingSlice {
bytes,
from_offset,
next_offset: from_offset + take as u64,
bytes_lost,
}
}
}
#[allow(dead_code)]
impl RxRing {
pub fn clear(&self) {
let mut inner = self.inner.lock().expect("ring mutex poisoned");
inner.start_offset = inner.end_offset;
}
pub async fn wait_for_data(&self, after: u64) {
loop {
let notified = self.notify.notified();
{
let inner = self.inner.lock().expect("ring mutex poisoned");
if inner.end_offset > after {
return;
}
}
notified.await;
}
}
}
#[allow(dead_code)]
fn write_ring(buf: &mut [u8], phys: usize, src: &[u8]) {
let cap = buf.len();
let end = phys + src.len();
if end <= cap {
buf[phys..end].copy_from_slice(src);
} else {
let first = cap - phys;
buf[phys..].copy_from_slice(&src[..first]);
buf[..end - cap].copy_from_slice(&src[first..]);
}
}
#[allow(dead_code)]
fn read_ring(buf: &[u8], phys: usize, take: usize) -> Vec<u8> {
let cap = buf.len();
let end = phys + take;
if end <= cap {
buf[phys..end].to_vec()
} else {
let first = cap - phys;
let mut out = Vec::with_capacity(take);
out.extend_from_slice(&buf[phys..]);
out.extend_from_slice(&buf[..take - first]);
out
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn new_ring_has_zero_offsets() {
let ring = RxRing::new(16);
assert_eq!(ring.start_offset(), 0);
assert_eq!(ring.end_offset(), 0);
assert_eq!(ring.capacity(), 16);
let slice = ring.read_from(0, 10);
assert!(slice.bytes.is_empty());
assert_eq!(slice.from_offset, 0);
assert_eq!(slice.next_offset, 0);
assert_eq!(slice.bytes_lost, 0);
}
#[test]
#[should_panic(expected = "RxRing capacity must be > 0")]
fn new_zero_capacity_panics() {
let _ring = RxRing::new(0);
}
#[test]
fn append_advances_end_offset() {
let ring = RxRing::new(16);
ring.append(b"abc");
assert_eq!(ring.start_offset(), 0);
assert_eq!(ring.end_offset(), 3);
}
#[test]
fn read_from_returns_appended_bytes() {
let ring = RxRing::new(16);
ring.append(b"abc");
let slice = ring.read_from(0, 10);
assert_eq!(slice.bytes, b"abc");
assert_eq!(slice.from_offset, 0);
assert_eq!(slice.next_offset, 3);
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn read_from_advances_cursor_via_next_offset() {
let ring = RxRing::new(16);
ring.append(b"abcdef");
let s1 = ring.read_from(0, 3);
assert_eq!(s1.bytes, b"abc");
assert_eq!(s1.next_offset, 3);
let s2 = ring.read_from(3, 3);
assert_eq!(s2.bytes, b"def");
assert_eq!(s2.next_offset, 6);
}
#[test]
fn read_from_respects_max() {
let ring = RxRing::new(16);
ring.append(b"abcdef");
let slice = ring.read_from(0, 3);
assert_eq!(slice.bytes.len(), 3);
assert_eq!(slice.bytes, b"abc");
assert_eq!(slice.next_offset, 3);
}
#[test]
fn read_from_zero_max_returns_empty() {
let ring = RxRing::new(16);
ring.append(b"abc");
let slice = ring.read_from(0, 0);
assert!(slice.bytes.is_empty());
assert_eq!(slice.from_offset, 0);
assert_eq!(slice.next_offset, 0);
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn read_from_clamps_cursor_above_end_offset() {
let ring = RxRing::new(16);
ring.append(b"abc"); let slice = ring.read_from(100, 10);
assert!(slice.bytes.is_empty());
assert_eq!(slice.from_offset, 3);
assert_eq!(slice.next_offset, 3);
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn append_empty_is_noop() {
let ring = RxRing::new(16);
ring.append(b"abc");
ring.append(b"");
assert_eq!(ring.start_offset(), 0);
assert_eq!(ring.end_offset(), 3);
let slice = ring.read_from(0, 10);
assert_eq!(slice.bytes, b"abc");
}
#[test]
fn append_wraps_and_drops_oldest() {
let ring = RxRing::new(4);
ring.append(b"abcd"); assert_eq!(ring.start_offset(), 0);
assert_eq!(ring.end_offset(), 4);
ring.append(b"efgh"); assert_eq!(ring.start_offset(), 4);
assert_eq!(ring.end_offset(), 8);
let slice = ring.read_from(4, 4);
assert_eq!(slice.bytes, b"efgh");
assert_eq!(slice.from_offset, 4);
assert_eq!(slice.next_offset, 8);
assert_eq!(slice.bytes_lost, 0);
let old = ring.read_from(0, 4);
assert_eq!(old.bytes_lost, 4);
assert_eq!(old.from_offset, 4); assert_eq!(old.bytes, b"efgh");
}
#[test]
fn append_larger_than_capacity_keeps_only_tail() {
let ring = RxRing::new(4);
ring.append(b"abcdefgh"); assert_eq!(ring.start_offset(), 4);
assert_eq!(ring.end_offset(), 8);
let slice = ring.read_from(4, 4);
assert_eq!(slice.bytes, b"efgh");
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn append_multiple_wraps_track_correctly() {
let ring = RxRing::new(4);
ring.append(b"ab"); ring.append(b"cd"); ring.append(b"ef"); ring.append(b"gh"); ring.append(b"ij");
let slice = ring.read_from(6, 4);
assert_eq!(slice.bytes, b"ghij");
assert_eq!(slice.from_offset, 6);
assert_eq!(slice.next_offset, 10);
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn read_from_wrap_reads_across_buffer_boundary() {
let ring = RxRing::new(4);
ring.append(b"abcdefg");
let slice = ring.read_from(3, 4);
assert_eq!(slice.bytes, b"defg");
assert_eq!(slice.from_offset, 3);
assert_eq!(slice.next_offset, 7);
}
#[test]
fn append_larger_than_capacity_wraps_and_writes_correctly() {
let ring = RxRing::new(4);
ring.append(b"abcdefg"); assert_eq!(ring.start_offset(), 3);
assert_eq!(ring.end_offset(), 7);
let slice = ring.read_from(3, 4);
assert_eq!(slice.bytes, b"defg");
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn read_from_gap_accounting_when_cursor_below_start() {
let ring = RxRing::new(4);
ring.append(b"abcd"); ring.append(b"efgh");
let slice = ring.read_from(2, 4);
assert_eq!(slice.bytes_lost, 2);
assert_eq!(slice.from_offset, 4);
assert_eq!(slice.bytes, b"efgh");
assert_eq!(slice.next_offset, 8);
}
#[test]
fn read_from_no_gap_when_cursor_equals_start() {
let ring = RxRing::new(4);
ring.append(b"abcd");
ring.append(b"efgh");
let slice = ring.read_from(4, 4);
assert_eq!(slice.bytes_lost, 0);
assert_eq!(slice.from_offset, 4);
}
#[test]
fn clear_resets_retained_start_catches_up_to_end() {
let ring = RxRing::new(16);
ring.append(b"abc");
assert_eq!(ring.start_offset(), 0);
assert_eq!(ring.end_offset(), 3);
ring.clear();
assert_eq!(ring.start_offset(), 3);
assert_eq!(ring.end_offset(), 3);
let slice = ring.read_from(0, 10);
assert_eq!(slice.bytes_lost, 3); assert!(slice.bytes.is_empty());
assert_eq!(slice.from_offset, 3);
assert_eq!(slice.next_offset, 3);
}
#[test]
fn clear_then_append_resumes_at_end_offset() {
let ring = RxRing::new(16);
ring.append(b"abc"); ring.clear();
ring.append(b"xy"); assert_eq!(ring.start_offset(), 3);
assert_eq!(ring.end_offset(), 5);
let slice = ring.read_from(3, 2);
assert_eq!(slice.bytes, b"xy");
assert_eq!(slice.from_offset, 3);
assert_eq!(slice.next_offset, 5);
assert_eq!(slice.bytes_lost, 0);
}
#[test]
fn read_from_caught_up_reader_gets_empty() {
let ring = RxRing::new(16);
ring.append(b"abc");
let slice = ring.read_from(3, 10);
assert!(slice.bytes.is_empty());
assert_eq!(slice.from_offset, 3);
assert_eq!(slice.next_offset, 3);
assert_eq!(slice.bytes_lost, 0);
}
#[tokio::test]
async fn wait_for_data_wakes_on_append() {
let ring = std::sync::Arc::new(RxRing::new(16));
let ring_clone = ring.clone();
let handle = tokio::spawn(async move {
ring_clone.wait_for_data(0).await;
});
tokio::task::yield_now().await;
ring.append(b"x");
handle.await.unwrap();
}
#[tokio::test]
async fn wait_for_data_returns_immediately_when_data_already_past_after() {
let ring = RxRing::new(16);
ring.append(b"abc");
ring.wait_for_data(2).await;
}
#[tokio::test]
async fn wait_for_data_spurious_wakeup_safe() {
let ring = std::sync::Arc::new(RxRing::new(16));
let ring_clone = ring.clone();
let handle = tokio::spawn(async move {
ring_clone.wait_for_data(0).await;
});
tokio::task::yield_now().await;
ring.notify.notify_waiters();
tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;
assert!(!handle.is_finished());
ring.append(b"x");
handle.await.unwrap();
}
#[tokio::test]
async fn wait_for_data_multiple_waiters_wake() {
let ring = std::sync::Arc::new(RxRing::new(16));
let r1 = {
let r = ring.clone();
tokio::spawn(async move { r.wait_for_data(0).await })
};
let r2 = {
let r = ring.clone();
tokio::spawn(async move { r.wait_for_data(0).await })
};
tokio::task::yield_now().await;
ring.append(b"hello");
r1.await.unwrap();
r2.await.unwrap();
}
#[test]
fn ring_is_send_and_sync() {
fn assert_send<T: Send>() {}
fn assert_sync<T: Sync>() {}
assert_send::<RxRing>();
assert_sync::<RxRing>();
}
#[test]
fn end_offset_never_decreases_across_clear() {
let ring = RxRing::new(16);
ring.append(b"hello");
let before = ring.end_offset();
ring.clear();
assert_eq!(ring.end_offset(), before);
}
#[test]
fn bytes_wrapped_total_accumulates_across_wraps_and_survives_clear() {
let ring = RxRing::new(4);
assert_eq!(ring.bytes_wrapped_total(), 0);
ring.append(b"abcdefgh");
assert_eq!(ring.bytes_wrapped_total(), 4);
let s1 = ring.read_from(2, 4);
assert_eq!(s1.bytes_lost, 2);
assert_eq!(ring.bytes_wrapped_total(), 4);
ring.append(b"ijklmnop");
assert_eq!(ring.bytes_wrapped_total(), 12);
ring.clear();
assert_eq!(ring.bytes_wrapped_total(), 12);
ring.append(b"qr");
assert_eq!(ring.bytes_wrapped_total(), 12);
}
mod proptest_tests {
use proptest::prelude::*;
proptest! {
#[test]
fn rx_ring_append_read_preserves_stream_and_offset_arithmetic(
ops in ops_strategy()
) {
let capacity = 4; let ring = super::RxRing::new(capacity);
let mut total_appended: u64 = 0;
let mut stream: Vec<u8> = Vec::new();
for op in ops {
match op {
Op::Append(data) => {
ring.append(&data);
stream.extend_from_slice(&data);
total_appended += data.len() as u64;
let expected_start = total_appended.saturating_sub(capacity as u64);
assert_eq!(ring.end_offset(), total_appended,
"end_offset mismatch after append");
assert_eq!(ring.start_offset(), expected_start,
"start_offset mismatch after append");
}
Op::Read { cursor, max } => {
let current_start = ring.start_offset();
let current_end = ring.end_offset();
let expected_bytes_lost = current_start.saturating_sub(cursor);
let expected_from = if cursor < current_start {
current_start
} else if cursor > current_end {
current_end
} else {
cursor
};
let available = if expected_from < current_end {
(current_end - expected_from) as usize
} else {
0
};
let take = max.min(available);
let model_start = expected_from as usize;
let model_end = model_start + take;
let expected_bytes: &[u8] = if model_start < stream.len() {
let end = model_end.min(stream.len());
&stream[model_start..end]
} else {
&[]
};
let slice = ring.read_from(cursor, max);
assert_eq!(slice.bytes_lost, expected_bytes_lost,
"bytes_lost mismatch");
assert_eq!(slice.from_offset, expected_from,
"from_offset mismatch");
if cursor > current_end {
assert!(slice.bytes.is_empty(),
"expected empty for cursor beyond end");
assert_eq!(slice.next_offset, current_end);
} else {
assert_eq!(slice.bytes, expected_bytes,
"data mismatch");
assert_eq!(slice.next_offset, expected_from + take as u64,
"next_offset mismatch");
}
}
}
}
}
}
#[derive(Debug, Clone)]
enum Op {
Append(Vec<u8>),
Read { cursor: u64, max: usize },
}
fn ops_strategy() -> impl Strategy<Value = Vec<Op>> {
let append = prop::collection::vec(0u8..=255u8, 0..32).prop_map(Op::Append);
let read = (0u64..32, 0usize..32).prop_map(|(cursor, max)| Op::Read { cursor, max });
prop::collection::vec(
prop::strategy::Union::new(vec![append.boxed(), read.boxed()]),
1..100,
)
}
}
}