Struct width_counters::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.

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 fn new() -> Self

Instantiate

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

Instantiate with ordering

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

Instantiate with offset value

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

Instantiate with offset value and ordering

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

Increment by one

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_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: 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 can_inc(&self) -> bool

Can the counter Incrementany further?

• It halts incrementing at Self::MAX

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

pub fn get_and_inc_one(&self) -> usize

Combine the increment (by one) and get operations

Returns the value before the incrementoperation

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 incrementoperation

impl CounterUsize

pub fn dec_one(&self)

Decrement by one

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_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: 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 can_dec(&self) -> bool

Can the counter Decrementany further?

• It halts decrementing at Self::MIN

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

pub fn get_and_dec_one(&self) -> usize

Combine the decrement (by one) and get operations

Returns the value before the decrementoperation

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 decrementoperation

Trait Implementations

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

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

Performs copy-assignment from source.

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<CounterUsize> 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 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 Mul<CounterUsize> 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) -> 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<CounterUsize> for CounterUsize

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

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<CounterUsize> 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

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<CounterUsize> 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