Struct CounterIsize

pub struct CounterIsize { /* private fields */ }

An atomic counter using AtomicIsize / (core::isize).

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 AtomicIsize, 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<isize>

Implementations

impl CounterIsize

pub const MAX: isize = 2_147_483_647isize

Largest representable value

pub const MIN: isize = -2_147_483_648isize

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

Instantiate with offset value

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

Instantiate with offset value and counting behavior

pub fn get(&self) -> isize

Get current value with the default ordering

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

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

Convert to some type that impls From isize.

impl CounterIsize

pub fn inc_one_with_ordering(&self, ordering: Ordering)

Increment by one with ordering

pub fn inc_by(&self, amount: isize)

Increment by specified amount

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

Increment by specified amount with ordering

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

Combine the increment (by one) and get operations

Returns the value before the increment operation

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

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

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

Returns the value before the increment operation

impl CounterIsize

pub fn dec_one_with_ordering(&self, ordering: Ordering)

Decrement by one with ordering

pub fn dec_by(&self, amount: isize)

Decrement by specified amount

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

Decrement by specified amount with ordering

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

Combine the decrement (by one) and get operations

Returns the value before the decrement operation

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

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

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

Returns the value before the decrement operation

Trait Implementations

impl Add for CounterIsize

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

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

type Output = CounterIsize

The resulting type after applying the + operator.

impl AsRef<Ordering> for CounterIsize

fn as_ref(&self) -> &Ordering

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

impl Clone for CounterIsize

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 CounterIsize

fn inc_one(&self)

Increment by one

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

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

Formats the value using the given formatter.

impl Default for CounterIsize

fn default() -> Self

Returns the “default value” for a type.

impl Display for CounterIsize

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

Formats the value using the given formatter.

impl Div for CounterIsize

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

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

type Output = CounterIsize

The resulting type after applying the / operator.

impl From<&CounterIsize> for isize

fn from(counter: &CounterIsize) -> Self

Converts to this type from the input type.

impl From<isize> for CounterIsize

fn from(x: isize) -> Self

Converts to this type from the input type.

impl HasCountingBehavior for CounterIsize

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

fn get_behavior_conflicts(&self) -> AllCountingBehaviorConflicts

impl Hash for CounterIsize

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 CounterIsize

type Unit = isize

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 CounterIsize

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

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

type Output = CounterIsize

The resulting type after applying the * operator.

impl Ord for CounterIsize

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 CounterIsize

PartialEq is only equal when orderings and counting behaviors are equal

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

PartialOrd only produces cmp ordering when atomic orderings are equal

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

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

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

type Output = CounterIsize

The resulting type after applying the - operator.

impl Eq for CounterIsize