Struct CounterUsize 

pub struct CounterUsize { /* private fields */ }

An atomic counter using AtomicUsize / (core::usize).

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 AtomicUsize, 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<usize>

Implementations

impl CounterUsize

pub const MAX: usize = 18_446_744_073_709_551_615usize

Largest representable value

pub const MIN: usize = 0usize

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: usize) -> Self

Instantiate with offset value

pub fn new_from_offset_with_ordering(offset: usize, 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: usize, counting_behavior: B, ) -> Self

Instantiate with offset value and counting behavior

pub fn get(&self) -> usize

Get current value with the default ordering

use width_counters::{ *, CounterUsize as C };
use usize 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) -> usize

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<usize>>(&self) -> X

Convert to some type that impls From usize.

impl CounterUsize

pub fn inc_one_with_ordering(&self, ordering: Ordering)

Increment by one with ordering

pub fn inc_by(&self, amount: usize)

Increment by specified amount

use width_counters::{ *, CounterUsize as C };
use core::ops::*; 
use usize 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: usize, ordering: Ordering)

Increment by specified amount with ordering

use width_counters::{ *, CounterUsize as C };
use usize as U;
use core::ops::*; 
let m = 3usize;
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) -> usize

Combine the increment (by one) and get operations

Returns the value before the increment operation

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

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: usize, ordering: Ordering, ) -> usize

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

Returns the value before the increment operation

impl CounterUsize

pub fn dec_one_with_ordering(&self, ordering: Ordering)

Decrement by one with ordering

pub fn dec_by(&self, amount: usize)

Decrement by specified amount

use width_counters::{ *, CounterUsize as C };
use core::ops::*; 
use usize 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: usize, ordering: Ordering)

Decrement by specified amount with ordering

use width_counters::{ *, CounterUsize as C };
use usize as U;
use core::ops::*; 
let m = 3usize;
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) -> usize

Combine the decrement (by one) and get operations

Returns the value before the decrement operation

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

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: usize, ordering: Ordering, ) -> usize

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

Returns the value before the decrement operation

Trait Implementations

impl Add for CounterUsize

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

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

type Output = CounterUsize

The resulting type after applying the + operator.

impl AsRef<Ordering> for CounterUsize

fn as_ref(&self) -> &Ordering

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

impl Clone for CounterUsize

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 CounterUsize

fn inc_one(&self)

Increment by one

use width_counters::{ *, CounterUsize as C };
use core::ops::*; 
use enumflags2::{make_bitflags};
use usize 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::{*, CounterUsize as C, CountingBehavior as B };
use usize as U;
use core::ops::*; 
let m = 3usize;
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::{ *, CounterUsize as C };
use core::ops::*; 
use enumflags2::{make_bitflags};
use usize 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::{*, CounterUsize as C, CountingBehavior as B };
use usize as U;
use core::ops::*; 
let m = 3usize;
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 CounterUsize

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

Formats the value using the given formatter.

impl Default for CounterUsize

fn default() -> Self

Returns the “default value” for a type.

impl Display for CounterUsize

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

Formats the value using the given formatter.

impl Div for CounterUsize

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

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

type Output = CounterUsize

The resulting type after applying the / operator.

impl From<&CounterUsize> for usize

fn from(counter: &CounterUsize) -> Self

Converts to this type from the input type.

impl From<usize> for CounterUsize

fn from(x: usize) -> Self

Converts to this type from the input type.

impl HasCountingBehavior for CounterUsize

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

fn get_behavior_conflicts(&self) -> AllCountingBehaviorConflicts

impl Hash for CounterUsize

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 CounterUsize

type Unit = usize

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 CounterUsize

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

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

type Output = CounterUsize

The resulting type after applying the * operator.

impl Ord for CounterUsize

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 CounterUsize

PartialEq is only equal when orderings and counting behaviors are equal

use width_counters::{ *, CounterUsize 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 CounterUsize

PartialOrd only produces cmp ordering when atomic orderings are equal

use width_counters::{ *, CounterUsize 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 CounterUsize

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

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

type Output = CounterUsize

The resulting type after applying the - operator.

impl Eq for CounterUsize