Struct metrics_util::AtomicBucket
source · [−]pub struct AtomicBucket<T> { /* private fields */ }Expand description
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
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.
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.
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.
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.