Struct width_counters::CounterU64

pub struct CounterU64 { /* private fields */ }

An atomic counter using AtomicU64 / (core::u64).

Behavior

1. The default ordering is Sequentially Consistent.
2. The ordering used for atomic operations is customizable for operations ending in with_ordering.
3. The choice of ordering intentionally impacts ALMOST EVERYTHING about how this counter works, including de/serialization, incrementing, decrementing, equality comparisons, partial ordering comparisons, etc.
4. Total (non-partial) ordering comparisons always use the default ordering.
5. Unlike the underlying AtomicU64, this will not wrap on overflow.

Ordering

• PartialEq is implemented such that counters with differing orderings are never equal.
• PartialOrd is implemented such that counters with differing (atomic) orderings produce no (comparison) ordering.
• (Saturating) arithmetic operations are implemented such that differing atomic orderings between the operands are ignored!

Miscellaneous

You can use the to_x method to convert to any type that implements From<u64>

Implementations

impl CounterU64

pub const MAX: u64 = 18_446_744_073_709_551_615u64

Largest representable value

pub const MIN: u64 = 0u64

Smallest representable value

pub const DEFAULT_ORDERING: Ordering = Ordering::SeqCst

Default Atomic ordering

pub const fn new() -> Self

Instantiate

pub const fn new_with_ordering(ordering: Ordering) -> Self

Instantiate with ordering

pub const fn new_from_offset(offset: u64) -> Self

Instantiate with offset value

pub const fn new_from_offset_with_ordering( offset: u64, ordering: Ordering ) -> Self

Instantiate with offset value and ordering

pub fn get(&self) -> u64

Get current value with the default ordering

use width_counters::{CounterU64 as C };
use u64 as U;
let c = C::new();
assert_eq!(c.get(), 0, "get returns initial value");
c.inc_one();
c.inc_one();
c.inc_one();
assert_eq!(c.get(), 3, "get returns post-increment value");

pub fn get_with_ordering(&self, ordering: Ordering) -> u64

Get current value with a specific ordering

pub fn get_i128(&self) -> i128

Convenience method for getting the current value as i128

pub fn to_x<X: From<u64>>(&self) -> X

Convert to some type that impls From u64.

impl CounterU64

pub fn inc_one(&self)

Increment by one

use width_counters::{CounterU64 as C };
use core::ops::*; 
use u64 as U;
let offset = U::MAX/2;
let c = C::new_from_offset(offset);
let m = 20;
(0..m).for_each(|_| { c.inc_one(); });
assert_eq!(c.get(), (offset).add(20), "counter must Increment/add number of times given as per sequential ordering");
let d = C::new_from_offset(U::MAX);
d.inc_one();
d.inc_one();
assert_eq!(d.get(), U::MAX, "counter must stop at MAX ");

pub fn inc_one_with_ordering(&self, ordering: Ordering)

Increment by one with ordering

pub fn inc_by(&self, amount: u64)

Increment by specified amount

use width_counters::{CounterU64 as C };
use core::ops::*; 
use u64 as U;
let offset = U::MAX/2;
let c = C::new_from_offset(offset);
let m = 20;
(0..m).for_each(|_| { c.inc_by(2); });
assert_eq!((c.get() as i128).sub((20*2) as i128), ((offset) as i128), "counter must Increment by specified amount");

pub fn inc_by_with_ordering(&self, amount: u64, ordering: Ordering)

Increment by specified amount with ordering

use width_counters::{CounterU64 as C };
use u64 as U;
use core::ops::*; 
let m = 3u64;
let offset = U::MAX/2;
let d = C::new_from_offset(U::MAX.sub(m * 2));
d.inc_by(m);
d.inc_by(m);
d.inc_by(m);
assert_eq!(d.get(), U::MAX, "counter must stop at MAX");

impl CounterU64

pub fn dec_one(&self)

Decrement by one

use width_counters::{CounterU64 as C };
use core::ops::*; 
use u64 as U;
let offset = U::MAX/2;
let c = C::new_from_offset(offset);
let m = 20;
(0..m).for_each(|_| { c.dec_one(); });
assert_eq!(c.get(), (offset).sub(20), "counter must Decrement/sub number of times given as per sequential ordering");
let d = C::new_from_offset(U::MIN);
d.dec_one();
d.dec_one();
assert_eq!(d.get(), U::MIN, "counter must stop at MIN ");

pub fn dec_one_with_ordering(&self, ordering: Ordering)

Decrement by one with ordering

pub fn dec_by(&self, amount: u64)

Decrement by specified amount

use width_counters::{CounterU64 as C };
use core::ops::*; 
use u64 as U;
let offset = U::MAX/2;
let c = C::new_from_offset(offset);
let m = 20;
(0..m).for_each(|_| { c.dec_by(2); });
assert_eq!((c.get() as i128).add((20*2) as i128), ((offset) as i128), "counter must Decrement by specified amount");

pub fn dec_by_with_ordering(&self, amount: u64, ordering: Ordering)

Decrement by specified amount with ordering

use width_counters::{CounterU64 as C };
use u64 as U;
use core::ops::*; 
let m = 3u64;
let offset = U::MAX/2;
let d = C::new_from_offset(U::MIN.add(m * 2));
d.dec_by(m);
d.dec_by(m);
d.dec_by(m);
assert_eq!(d.get(), U::MIN, "counter must stop at MIN");

Trait Implementations

impl Add<CounterU64> for CounterU64

fn add(self, rhs: Self) -> Self::Output

• This operation is implemented with saturating arithmetic
• This operation IGNORES dissimilar atomic orderings!

type Output = CounterU64

The resulting type after applying the + operator.

impl AsRef<Ordering> for CounterU64

fn as_ref(&self) -> &Ordering

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for CounterU64

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CounterU64

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

Formats the value using the given formatter.

impl Default for CounterU64

fn default() -> Self

Returns the “default value” for a type.

impl Display for CounterU64

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

Formats the value using the given formatter.

impl Div<CounterU64> for CounterU64

fn div(self, rhs: Self) -> Self::Output

• This operation is implemented with saturating arithmetic
• This operation IGNORES dissimilar atomic orderings!

type Output = CounterU64

The resulting type after applying the / operator.

impl From<&CounterU64> for u64

fn from(counter: &CounterU64) -> Self

Converts to this type from the input type.

impl From<u64> for CounterU64

fn from(x: u64) -> Self

Converts to this type from the input type.

impl Hash for CounterU64

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul<CounterU64> for CounterU64

fn mul(self, rhs: Self) -> Self::Output

• This operation is implemented with saturating arithmetic
• This operation IGNORES dissimilar atomic orderings!

type Output = CounterU64

The resulting type after applying the * operator.

impl Ord for CounterU64

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<CounterU64> for CounterU64

PartialEq is only equal when orderings are equal

use width_counters::{CounterU64 as C };
use core::sync::atomic::Ordering;
let a = C::new_from_offset_with_ordering(33, Ordering::Relaxed);
let b = C::new_from_offset_with_ordering(33, Ordering::Relaxed);
assert_eq!(a, b, "counters must be equal when counts and orderings are equal");
assert_eq!(a, b, "counters must be equal when counts and orderings are equal");
let m = 20;
(0..m).for_each(|_| { a.inc_one(); b.inc_one(); });
assert_eq!(a, b, "counters must be equal after counting same amount");
assert_eq!(a, b, "counters must be equal after counting same amount");
a.inc_one();
assert_ne!(a, b, "counters must not be equal after counting different amounts");
let c = C::new_from_offset_with_ordering(44, Ordering::Relaxed);
let d = C::new_from_offset_with_ordering(44, Ordering::Release);
assert_ne!(c, d, "ordering-inequal counters must not be equal with same count");

fn eq(&self, rhs: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<CounterU64> for CounterU64

PartialOrd only produces cmp ordering when atomic orderings are equal

use width_counters::{CounterU64 as C };
use core::sync::atomic::Ordering;
let a = C::new_from_offset_with_ordering(32, Ordering::Relaxed);
let b = C::new_from_offset_with_ordering(33, Ordering::Relaxed);
assert!(a < b, "same-cmp::ordering counters must be ordered by when counts");
assert!(b > a, "same-cmp::ordering counters must be ordered by when counts");
let m = 20;
(0..m).for_each(|_| { a.inc_one(); b.inc_one(); });
assert!(a < b, "cmp::ordering preserved after counting same amount");
assert!(b > a, "cmp::ordering preserved after counting same amount");

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<CounterU64> for CounterU64

fn sub(self, rhs: Self) -> Self::Output

• This operation is implemented with saturating arithmetic
• This operation IGNORES dissimilar atomic orderings!

type Output = CounterU64

The resulting type after applying the - operator.

impl Eq for CounterU64