Struct global_counter::primitive::fast::ApproxCounterU64

pub struct ApproxCounterU64 { /* fields omitted */ }

A global approximate counter.

This counter operates by having a local counter for each thread, which is occasionally flushed to the main global counter.

The accuracy of the counter is determined by its resolution and the number of threads counting on it: The value returned by get is guaranteed to always be less than or to equal this number of threads multiplied with the resolution minus one away from the actual amount of times inc has been called (+ start offset):

|get - (actual + start)| <= num_threads * (resolution - 1)

With resolution being >= 1. This is the only guarantee made.

Setting the resolution to 0 or 1 will just make it a worse primitive counter, don’t do that. Increasing the resolution increases this counters performance.

This counter also features a flush method, which can be used to manually flush the local counter of the current thread.

Note that this counters inc - (flush) - get - path does not induce a happens-before relationship, just like the flushing counters.

Implementations

impl ApproxCounterU64

pub const fn new(start: u64, resolution: u64) -> Self

Creates a new counter, with the given start value and resolution. Can be used in static contexts.

The start value is a lower bound for the value returned by get, not guaranteed to be the exact value on subsequent calls.

pub fn inc(&self)

Increments the counter by one.

Note that this call will probably leave the value returned by get unchanged.

pub fn get(&self) -> u64

Gets the current value of the counter. For more information, see the struct-level documentation.

Especially note, that two calls to get with one inc interleaved are not guaranteed to, and almost certainely wont, return different values.

pub fn flush(&self)

Flushes the local counter to the global.

Note that this only means the local counter of the thread calling is flushed. If you want to flush the local counters of multiple threads, each thread needs to call this method.

If every thread which incremented this counter has flushed its local counter, and no other increments have been made nor are being made, a subsequent call to get is guaranteed to return the exact count. However, if you can make use of this, consider if a flushing counter fits your usecase better.