Struct FifoDescriptor 

#[repr(C)]
pub struct FifoDescriptor<T> {
    pub data: *mut WithId<T>,
    pub len: usize,
    pub offsets: *const AtomicUsize,
}

A circular buffer used as a FIFO queue with atomic reads and writes.

The read offset is the element that was most recently read by the receiving end of the queue. The write offset is the element that was most recently written by the sending end. If the two offsets are equal, the queue is either empty or full.

The size of the buffer is such that not all the bits of the offset are necessary to encode the current offset. The next highest unused bit is used to keep track of the number of times the offset has wrapped around. If the offsets are the same and the bit is the same in the read and write offsets, the queue is empty. If the bit is different in the read and write offsets, the queue is full.

The following procedures will operate the queues in a multiple producer single consumer (MPSC) fashion.

Push operation

To push an element onto the queue:

1. Load the current offsets.
2. If the queue is full, wait, then go to step 1.
3. Add 1 to the write offset and do an atomic compare-and-swap (CAS) with the current offsets. If the CAS was not successful, go to step 1.
4. Write the data, then the id.
5. If the queue was empty in step 1, signal the reader to wake up.

Pop operation

To pop an element off the queue:

1. Load the current offsets.
2. If the queue is empty, wait, then go to step 1.
3. Add 1 to the read offset.
4. Read the id at the new read offset.
5. If id is 0, go to step 4 (spin). Spinning is OK because data is expected to be written imminently.
6. Read the data, then store 0 in the id.
7. Store the new read offset, retrieving the old offsets.
8. If the queue was full before step 7, signal the writer to wake up.

Fields

data: *mut WithId<T>

Pointer to the queue memory. Must have a size of len * size_of::<WithId<T>>() bytes and have alignment align_of::<WithId<T>>.

len: usize

The number of elements pointed to by data. Must be a power of two less than or equal to 2³¹.

offsets: *const AtomicUsize

Actually a (u32, u32) tuple, aligned to allow atomic operations on both halves simultaneously. The first element (low dword) is the read offset and the second element (high dword) is the write offset.

Trait Implementations

impl<T> Clone for FifoDescriptor<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Copy for FifoDescriptor<T>