Expand description
Simple, fast and self-contained structs for tracking whether a newly observed
value (u64
) is greater than the largest previously observed value.
Use cases include message sequence numbers, timestamps, and other situations that present a need to quickly assess whether incoming data is “new”, i.e. its numbering is larger than any previous value.
All of the structs include an is_new
function that returns true
if the
passed value is a new maximum, while simultaneously storing the new value to
check against future values.
Two of the is_new
implementations (Incr
and Map
) require an &mut self
signature, while RcIncr
and AtomicIncr
and AtomicMap
require only &self
due to RcIncr
’s interior mutability and AtomicIncr
’s thread safe syncrhonization.
The cost of checking a new value is minimal: 0-2ns for the single-threaded
implementations, and ~5-10ns for AtomicIncr
, except in cases of pathological
contention. In a worst-case, nightmare scenrio benchmark for the AtomicIncr
,
it’s possible to induce delays of hundreds of nanoseconds. A more realistic
case of 24 threads contending to increment the atomic but yielding each iteration
resulted in checks in the ~5-10ns range.
Enabling the “nightly” feature (on by default) allows the use of AtomicU64
as the backing storage for AtomicIncr
(vs. AtomicUsize
otherwise). Also,
nightly is required to run the benchmarks.
Enabling the “fnv” feature will use a Fowler-Noll-Vo hash function from the fnv
crate for the HashMap
used by Map
and AtomicMap
. FNV is faster than the
default hasher but provides no protection against malicious inputs.
Structs
AtomicIncr
is a threadsafe, yet very fast counter, utilizing compare and swap instructions to provide speed and safety in the same package. There are some cases where 5ns matters. But in many, many other situations, it’s a perfectly good decision to just use theAtomicIncr
, knowing it can handle anything, and move on to other problems.- Like
Map
,AtomicMap
provides simple, fast sequence checking by key, but with the thread-safe backing storage ofAtomicIncr
. - A self-contained struct for quickly checking whether a newly observed value is greater than any previously observed value.
- A map interface allowing fast checks of whether a newly observed value is greater than any previously observed value for a given key.
- The
Rc<Cell<_>>
backed storage ofRcIncr
provides flexibility in situations where the counter must be shared among several disparate objects/contexts while retaining consistentcy between all the references of the count.RcIncr
is not threadsafe, and even in single-threaded codeRc<Cell<T>>
has some tricky edge cases, for instance if aCell<T>
is used as the key to a hash map and the interior value mutated (fair warning).