Struct 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 unless the cyclic behavior mode is set.
6. The default behavior is non-monotonic, so the counter can increment and decrement.

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 DEFAULT_COUNTING_BEHAVIOR: BitFlags<CountingBehavior>

Default counting behavior

pub fn new() -> Self

Instantiate

pub fn new_with_ordering(ordering: Ordering) -> Self

Instantiate with ordering

pub fn new_from_offset(offset: u64) -> Self

Instantiate with offset value

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

Instantiate with offset value and ordering

pub fn set_counting_behavior<B: Into<BitFlags<CountingBehavior>>>( &mut self, counting_behavior: B, )

Set counting behavior

pub fn new_with_counting_behavior<B: Into<BitFlags<CountingBehavior>>>( counting_behavior: B, ) -> Self

Instantiate with counting behaviors

pub fn new_from_offset_with_counting_behavior<B: Into<BitFlags<CountingBehavior>>>( offset: u64, counting_behavior: B, ) -> Self

Instantiate with offset value and counting behavior

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_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 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");

pub fn get_and_inc_one(&self) -> u64

Combine the increment (by one) and get operations

Returns the value before the increment operation

pub fn get_and_inc_by(&self, amount: u64) -> u64

Combine the increment (by the given amount) and get operations

Returns the value before the incrementoperation

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

Combine the increment (by the given amount) and get operations

Returns the value before the increment operation

impl CounterU64

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 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");

pub fn get_and_dec_one(&self) -> u64

Combine the decrement (by one) and get operations

Returns the value before the decrement operation

pub fn get_and_dec_by(&self, amount: u64) -> u64

Combine the decrement (by the given amount) and get operations

Returns the value before the decrementoperation

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

Combine the decrement (by the given amount) and get operations

Returns the value before the decrement operation

Trait Implementations

impl Add 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 duplicate of the value.

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

Performs copy-assignment from source.

impl CountsNonmotonically for CounterU64

fn inc_one(&self)

Increment by one

use width_counters::{ *, CounterU64 as C };
use core::ops::*; 
use enumflags2::{make_bitflags};
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 ");

fn can_inc(&self) -> bool

Can the counter increment any further?

• It halts increment ing at Self::MAX

use width_counters::{*, CounterU64 as C, CountingBehavior as B };
use u64 as U;
use core::ops::*; 
let m = 3u64;
let offset = C::MAX/2;
let d = C::new_from_offset_with_counting_behavior(offset, B::Increment);
assert_eq!(d.can_inc(), true, "counter must detect when it can Increment");
let offset = C::MAX;
let d = C::new_from_offset_with_counting_behavior(offset, B::Increment);
assert_eq!(d.can_inc(), false, "counter must detect when it can no longer Increment");

fn is_incrementable(&self) -> bool

Is the current index advanceable with the given operation type

fn is_within_increment_bound(&self) -> bool

Is it within(inclusive) the increment bound

• The bound is: Self::MAX
• The bound never applies in:** acyclic mode

fn is_at_increment_bound(&self) -> bool

Is it at the increment bound

• The bound is: Self::MAX

fn dec_one(&self)

Decrement by one

use width_counters::{ *, CounterU64 as C };
use core::ops::*; 
use enumflags2::{make_bitflags};
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 ");

fn can_dec(&self) -> bool

Can the counter decrement any further?

• It halts decrement ing at Self::MIN

use width_counters::{*, CounterU64 as C, CountingBehavior as B };
use u64 as U;
use core::ops::*; 
let m = 3u64;
let offset = C::MAX/2;
let d = C::new_from_offset_with_counting_behavior(offset, B::Decrement);
assert_eq!(d.can_dec(), true, "counter must detect when it can Decrement");
let offset = C::MIN;
let d = C::new_from_offset_with_counting_behavior(offset, B::Decrement);
assert_eq!(d.can_dec(), false, "counter must detect when it can no longer Decrement");

fn is_decrementable(&self) -> bool

Is the current index advanceable with the given operation type

fn is_within_decrement_bound(&self) -> bool

Is it within(inclusive) the decrement bound

• The bound is: Self::MIN
• The bound never applies in:** acyclic mode

fn is_at_decrement_bound(&self) -> bool

Is it at the decrement bound

• The bound is: Self::MIN

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 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 HasCountingBehavior for CounterU64

fn get_behavior_ref(&self) -> &BitFlags<CountingBehavior>

fn get_behavior_conflicts(&self) -> AllCountingBehaviorConflicts

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 IsCounter for CounterU64

type Unit = u64

fn get_ordering_ref(&self) -> &Ordering

Get the ordering

fn get_current(&self) -> Self::Unit

Get the current value with the preset ordering

impl Mul 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) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for CounterU64

PartialEq is only equal when orderings and counting behaviors 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

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd 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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Sub 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