Struct AtomicRingBuf 

pub struct AtomicRingBuf<T: AtomicElement, const N: usize, const OVERWRITE: bool = true> { /* private fields */ }

Ring buffer specialized for atomic types

为原子类型特化的环形缓冲区

Type Parameters

• T: Atomic type implementing AtomicElement
• N: Stack capacity threshold
• OVERWRITE: Overwrite mode (true = overwrite oldest, false = reject when full)

类型参数

• T: 实现 AtomicElement 的原子类型
• N: 栈容量阈值
• OVERWRITE: 覆盖模式（true = 覆盖最旧的，false = 满时拒绝）

Implementations

impl<T: AtomicElement, const N: usize, const OVERWRITE: bool> AtomicRingBuf<T, N, OVERWRITE>

pub fn new(capacity: usize) -> Self

where T: Default,

Create a new atomic ring buffer

创建新的原子环形缓冲区

pub fn new_uninit(capacity: usize) -> Self

Create a new atomic ring buffer with uninitialized elements

创建新的原子环形缓冲区，元素未初始化

pub fn capacity(&self) -> usize

Get capacity

获取容量

pub fn len(&self) -> usize

Get current length

获取当前长度

pub fn is_empty(&self) -> bool

Check if empty

检查是否为空

pub fn is_full(&self) -> bool

Check if full

检查是否已满

pub fn push( &self, value: T::Primitive, order: Ordering, ) -> <PushMarker<OVERWRITE> as PushDispatch<T, N, OVERWRITE>>::PushOutput

where PushMarker<OVERWRITE>: PushDispatch<T, N, OVERWRITE>,

Push a value into the buffer

向缓冲区推送一个值

Behavior

• Overwrite mode (OVERWRITE=true): Always succeeds. Returns Some(T::Primitive) if an element was overwritten, None otherwise.
• Non-overwrite mode (OVERWRITE=false): Returns Err(value) if buffer is full, Ok(()) otherwise.

行为

• 覆盖模式 (OVERWRITE=true): 总是成功。如果覆盖了元素则返回 Some(T::Primitive)，否则返回 None。
• 非覆盖模式 (OVERWRITE=false): 如果缓冲区满则返回 Err(value)，否则返回 Ok(())。

Examples

use smallring::atomic::{AtomicRingBuf, AtomicElement};
use std::sync::atomic::{AtomicU64, Ordering};

// Overwrite mode
let buf_ow: AtomicRingBuf<AtomicU64, 32, true> = AtomicRingBuf::new(2);
assert_eq!(buf_ow.push(1, Ordering::Relaxed), None);
assert_eq!(buf_ow.push(2, Ordering::Relaxed), None);
assert_eq!(buf_ow.push(3, Ordering::Relaxed), Some(1)); // Overwrote 1

// Non-overwrite mode
let buf_no: AtomicRingBuf<AtomicU64, 32, false> = AtomicRingBuf::new(2);
assert_eq!(buf_no.push(1, Ordering::Relaxed), Ok(()));
assert_eq!(buf_no.push(2, Ordering::Relaxed), Ok(()));
assert_eq!(buf_no.push(3, Ordering::Relaxed), Err(3)); // Full

pub fn pop(&self, order: Ordering) -> Option<T::Primitive>

Pop a value from the buffer

从缓冲区弹出一个值

pub fn peek(&self, order: Ordering) -> Option<T::Primitive>

Peek at the next value without removing it

查看下一个值但不移除

pub unsafe fn get_unchecked(&self, offset: usize) -> &T

Access a slot directly by offset from read position

通过从读位置的偏移直接访问槽位

Safety

Caller must ensure offset < len()

pub fn clear(&self)

Clear all elements from the buffer

清空缓冲区中的所有元素

Resets the buffer to empty state by synchronizing read and write indices.

通过同步读写索引将缓冲区重置为空状态。

Examples

use smallring::atomic::AtomicRingBuf;
use std::sync::atomic::{AtomicU64, Ordering};

let buf: AtomicRingBuf<AtomicU64, 32> = AtomicRingBuf::new(8);
buf.push(1, Ordering::Relaxed);
buf.push(2, Ordering::Relaxed);
assert_eq!(buf.len(), 2);

buf.clear();
assert_eq!(buf.len(), 0);
assert!(buf.is_empty());

pub fn read_all(&self, order: Ordering) -> Vec<T::Primitive>

Read all valid elements from the buffer

读取缓冲区中所有有效元素

Returns a vector of all elements currently in the buffer, in FIFO order. This does not remove elements from the buffer.

返回缓冲区中当前所有元素的向量，按 FIFO 顺序排列。 此操作不会从缓冲区中移除元素。

Examples

use smallring::atomic::AtomicRingBuf;
use std::sync::atomic::{AtomicU64, Ordering};

let buf: AtomicRingBuf<AtomicU64, 32> = AtomicRingBuf::new(8);
buf.push(1, Ordering::Relaxed);
buf.push(2, Ordering::Relaxed);
buf.push(3, Ordering::Relaxed);

let values = buf.read_all(Ordering::Acquire);
assert_eq!(values, vec![1, 2, 3]);
assert_eq!(buf.len(), 3); // Elements still in buffer

pub fn iter(&self) -> AtomicIter<'_, T, N, OVERWRITE>

Get an iterator over elements in the buffer

获取缓冲区元素的迭代器

Returns an iterator that yields references to atomic elements in FIFO order. The iterator provides read-only access to the underlying atomic values.

返回一个按 FIFO 顺序产生原子元素引用的迭代器。 迭代器提供对底层原子值的只读访问。

Examples

use smallring::atomic::AtomicRingBuf;
use std::sync::atomic::{AtomicU64, Ordering};

let buf: AtomicRingBuf<AtomicU64, 32> = AtomicRingBuf::new(8);
buf.push(1, Ordering::Relaxed);
buf.push(2, Ordering::Relaxed);
buf.push(3, Ordering::Relaxed);

let values: Vec<u64> = buf.iter()
    .map(|atom| atom.load(Ordering::Acquire))
    .collect();
assert_eq!(values, vec![1, 2, 3]);

impl<T: AtomicElement + AtomicNumeric, const N: usize, const OVERWRITE: bool> AtomicRingBuf<T, N, OVERWRITE>

pub unsafe fn fetch_add_at( &self, offset: usize, val: T::Primitive, order: Ordering, ) -> T::Primitive

Atomically add to an element at the given offset from read position

原子地将值加到从读位置开始的给定偏移处的元素

Safety

Caller must ensure offset < len()

Examples

use smallring::atomic::AtomicRingBuf;
use std::sync::atomic::{AtomicU64, Ordering};

let buf: AtomicRingBuf<AtomicU64, 32> = AtomicRingBuf::new(8);
buf.push(10, Ordering::Relaxed);
buf.push(20, Ordering::Relaxed);

// Add 5 to the first element
let old = unsafe { buf.fetch_add_at(0, 5, Ordering::Relaxed) };
assert_eq!(old, 10);
assert_eq!(buf.peek(Ordering::Acquire).unwrap(), 15);

pub unsafe fn fetch_sub_at( &self, offset: usize, val: T::Primitive, order: Ordering, ) -> T::Primitive

Atomically subtract from an element at the given offset from read position

原子地从读位置开始的给定偏移处的元素减去值

Safety

Caller must ensure offset < len()

Trait Implementations

impl<T: AtomicElement, const N: usize, const OVERWRITE: bool> Debug for AtomicRingBuf<T, N, OVERWRITE>

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

Formats the value using the given formatter.

impl<T: AtomicElement, const N: usize, const OVERWRITE: bool> Send for AtomicRingBuf<T, N, OVERWRITE>

impl<T: AtomicElement, const N: usize, const OVERWRITE: bool> Sync for AtomicRingBuf<T, N, OVERWRITE>