Struct width_counters::CounterU64

pub struct CounterU64 { /* private fields */ }

A monotonically increasing 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 EVERYTHING about how this counter works, including de/serialization, incrementing, jumping, equality comparisons, partial ordering comparisons, etc.
4. Total (non-partial) ordering comparisons always use the default ordering.

Other Notes

• 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.
• Unlike the underlying AtomicU64, this will not wrap on overflow.

Implementations

impl CounterU64

pub const MAX: u64 = 18_446_744_073_709_551_615u64

Largest 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();
c.inc();
c.inc();
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 inc(&self)

Increment by one

use width_counters::{CounterU64 as C };
use u64 as U;
let c = C::new();
let m = 20;
(0..m).for_each(|_| { c.inc(); });
assert_eq!(c.get(), 20, "counter must count number of times given as per sequential ordering");
let d = C::new_from_offset(U::MAX);
d.inc();
d.inc();
assert_eq!(d.get(), U::MAX, "counter must stop at maximum");

pub fn inc_with_ordering(&self, ordering: Ordering)

Increment by one with ordering

pub fn jump(&self, amount: u64)

Jump by specified amount

use width_counters::{CounterU64 as C };
use u64 as U;
let c = C::default();
let m = 20;
(0..m).for_each(|_| { c.jump(2); });
assert_eq!(c.get(), 20*2, "counter must jump by specified amount");

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

Jump by specified amount with ordering

use width_counters::{CounterU64 as C };
use u64 as U;
let c = C::new();
let m: U = 20;
(0..m).for_each(|_| { c.jump(2); });
assert_eq!(c.get(), 40, "counter must jump by specified amount");
let d = C::new_from_offset(U::MAX - m);
d.jump(m/3);
d.jump(m/3);
d.jump(m/2);
assert_eq!(d.get(), U::MAX, "counter must stop at maximum");

Trait Implementations

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 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 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(); b.inc(); });
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();
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(); b.inc(); });
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 Eq for CounterU64