Struct MultiBuffer 

pub struct MultiBuffer<T, const SIZE: usize> { /* private fields */ }

A generic multi-buffering structure designed for lock-free concurrency, supporting a configurable number of buffers, each tagged with a version number for tracking updates.

Type Parameters

• T: The type of data stored in each buffer.
• SIZE: The number of buffers in the structure, which is fixed at compile time.

Structure

• Each buffer has an associated tag (u64) to track its version or state. This allows consumers to determine if a specific buffer contains newer data.
• An internal fence pointer is used to indicate the latest published buffer.

Safety

• The buffers are wrapped in UnsafeCell to allow efficient mutable access without synchronization primitives.
• The implementation assumes the user correctly follows the API’s safety guarantees to avoid undefined behavior, especially when using methods like get_mut and publish in a concurrent environment.
• Correct use of the API ensures that data remains consistent and race conditions are avoided.

Usage

This structure is particularly useful in scenarios requiring efficient lock-free communication of data across threads, such as real-time processing or streaming.

Implementations

impl<T, const SIZE: usize> MultiBuffer<T, SIZE>

pub const SIZE: usize = SIZE

The number of buffers in the structure, determined at compile-time.

pub const fn len(&self) -> usize

Returns the number of buffers in the structure.

This is a constant value defined by the SIZE generic parameter.

impl<T, const SIZE: usize> MultiBuffer<T, SIZE>

pub fn new(factory: impl FnMut() -> T) -> Self

Creates a new MultiBuffer with the specified size and initializes each buffer with the provided factory function.

Parameters

• factory: A function or closure that produces an initial value for each buffer.

Returns

A new instance of MultiBuffer initialized with the values created by the factory.

Panics

This method will panic if the factory function panics during initialization.

pub fn get_latest(&self) -> (&T, BufferTag)

Retrieves a reference to the latest published buffer.

Returns

A reference to the data in the buffer that was most recently published, along with its associated version tag.

Safety

• The method assumes that the underlying concurrency rules are correctly followed and guarantees a consistent snapshot of the latest buffer.
• The version tag provides a mechanism to track updates and ensure consumers can identify if they are working with the most recent data or detect stale reads.
• This method uses UnsafeCell dereferencing internally, which is safe as long as only one thread is modifying the buffer while others are reading it.

pub fn get_mut(&self, index: BufferIndex) -> &mut T

Retrieves a mutable reference to a specific buffer by its index.

Parameters

• index: The index of the buffer to retrieve.

Returns

A mutable reference to the specified buffer.

Safety

• The caller must ensure that the accessed buffer is not being simultaneously read or written from another thread.
• This method uses internal UnsafeCell dereferencing, which assumes the correct usage of MultiBuffer’s API in a concurrent context.

pub fn publish(&self, index: BufferIndex, version: BufferTag)

Publishes a specific buffer by updating the internal fence and its version tag.

Parameters

• index: The index of the buffer to publish.
• version: The version tag to assign to the buffer being published.

Safety

• The caller must ensure that the buffer being published is fully modified and in a valid state before calling this method.
• This method uses memory ordering guarantees (Release) to ensure that the changes made to the buffer are visible to other threads before the publish operation completes.
• It is the caller’s responsibility to prevent data races by adhering to proper concurrent usage patterns.

Trait Implementations

impl<T, const SIZE: usize> Sync for MultiBuffer<T, SIZE>