fast_counter/
lib.rs

1//! Fast-counter is a shareded concurrent atomic counter
2//!
3//! The library works by sharding the atomic numbers between multiple values, each thread will
4//! attempt to read from a different cell. This helps with cache-thrashing and contention. This
5//! benefit is seen when there is a greater number of threads competing over a single cell, on my
6//! machine with 16 cores attempting to update the value it can be nearly 60x faster. The price you
7//! pay for this is higher memory usage as we have multiple Atomic numbers which are cache-padded
8//! so can be significantly higher.
9//!
10//! # Usage
11//!
12//! Usage of the library is simple, create a new ConcurrentCounter with then  number of shards you
13//! wish to have, internally the library will use the next power of two as the number of cells for
14//! a faster modulus.
15//!
16//! ```rust
17//! use fast_counter::ConcurrentCounter;
18//!
19//! let counter = ConcurrentCounter::new(10);
20//!
21//! counter.add(1);
22//!
23//! let sum = counter.sum();
24//!
25//! assert_eq!(sum, 1);
26//! ```
27//!
28//! # Performance considerations
29//!
30//! The library will perform best when the threads are accessing their own cell consistently. This
31//! can helped by making sure more than enough cells are allocated for the number of threads which
32//! are going to be writing to the cell. 
33//!
34//! Due to the sharding behaviour the time to call the `sum()` method does slow down with the
35//! increase in shards, if this becomes a bottleneck it may be worth investigating running with a
36//! lower shard counter
37//!
38
39#[macro_use]
40mod safe_getters;
41mod utils;
42
43pub mod counter;
44pub use counter::*;