Struct metrics_util::AtomicBucket

pub struct AtomicBucket<T> { /* fields omitted */ }

A lock-free bucket with snapshot capabilities.

This bucket is implemented as a singly-linked list of blocks, where each block is a small buffer that can hold a handful of elements. There is no limit to how many elements can be in the bucket at a time. Blocks are dynamically allocated as elements are pushed into the bucket.

Unlike a queue, buckets cannot be drained element by element: callers must iterate the whole structure. Reading the bucket happens in a quasi-reverse fashion, to allow writers to make forward progress without affecting the iteration of the previously written values.

For example, in a scenario where an internal block can hold 4 elements, and the caller has written 10 elements to the bucket, you would expect to see the values in this order when iterating:

[6 7 8 9] [2 3 4 5] [0 1]

Block sizes are dependent on the target architecture, where each block can hold N items, and N is the number of bits in the target architecture’s pointer width.

Implementations

impl<T> AtomicBucket<T>

pub fn new() -> Self

Creates a new, empty bucket.

pub fn is_empty(&self) -> bool

Checks whether or not this bucket is empty.

pub fn push(&self, value: T)

Pushes an element into the bucket.

pub fn data(&self) -> Vec<T> where
    T: Clone, 

Collects all of the elements written to the bucket.

This operation can be slow as it involves allocating enough space to hold all of the elements within the bucket. Consider data_with to incrementally iterate the internal blocks within the bucket.

Elements are in partial reverse order: blocks are iterated in reverse order, but the elements within them will appear in their original order.

pub fn data_with<F>(&self, f: F) where
    F: FnMut(&[T]), 

Iterates all of the elements written to the bucket, invoking f for each block.

Elements are in partial reverse order: blocks are iterated in reverse order, but the elements within them will appear in their original order.

pub fn clear(&self)

Clears the bucket.

Deallocation of the internal blocks happens only when all readers have finished, and so will not necessarily occur during or immediately preceding this method.

Note

This method will not affect reads that are already in progress.

pub fn clear_with<F>(&self, f: F) where
    F: FnMut(&[T]), 

Clears the bucket, invoking f for every block that will be cleared.

Deallocation of the internal blocks happens only when all readers have finished, and so will not necessarily occur during or immediately preceding this method.

This method is useful for accumulating values and then observing them, in a way that allows the caller to avoid visiting the same values again the next time.

This method allows a pattern of observing values before they’re cleared, with a clear demarcation. A similar pattern used in the wild would be to have some data structure, like a vector, which is continuously filled, and then eventually swapped out with a new, empty vector, allowing the caller to read all of the old values while new values are being written, over and over again.

Note

This method will not affect reads that are already in progress.

Trait Implementations

impl<T: Debug> Debug for AtomicBucket<T>

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

Formats the value using the given formatter.

impl<T> Default for AtomicBucket<T>

fn default() -> Self

Returns the “default value” for a type.