Struct AtomicCount 

pub struct AtomicCount { /* private fields */ }

A non-negative atomic counter with synchronization-oriented operations.

Use this type when the counter value is part of a concurrent state machine, such as active task counts, in-flight request counts, resource usage counts, or shutdown and termination checks. Its operations return the value after the update, which makes zero-transition logic straightforward.

For pure metrics, statistics, event counters, or ID generation, prefer the regular atomic integer types such as Atomic<usize>. Those types keep arithmetic operations lightweight for pure counting.

This counter never wraps. Incrementing past usize::MAX panics, and decrementing below zero panics. Use try_add, try_dec, or try_sub when overflow or underflow is a normal business outcome.

Example

use qubit_atomic::AtomicCount;

let active_tasks = AtomicCount::zero();

active_tasks.inc();
assert!(!active_tasks.is_zero());

if active_tasks.dec() == 0 {
    // The last active task finished; notify termination waiters here.
}

Author

Haixing Hu

Implementations

impl AtomicCount

pub const fn new(value: usize) -> Self

Creates a new non-negative atomic counter.

Parameters

• value - The initial counter value.

Returns

A counter initialized to value.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(3);
assert_eq!(counter.get(), 3);

pub const fn zero() -> Self

Creates a new counter initialized to zero.

Returns

A counter whose current value is zero.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::zero();
assert!(counter.is_zero());

pub fn get(&self) -> usize

Gets the current counter value.

Returns

The current counter value.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(7);
assert_eq!(counter.get(), 7);

pub fn is_zero(&self) -> bool

Returns whether the current counter value is zero.

Returns

true if the current value is zero, otherwise false.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::zero();
assert!(counter.is_zero());

pub fn is_positive(&self) -> bool

Returns whether the current counter value is greater than zero.

Returns

true if the current value is greater than zero, otherwise false.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(1);
assert!(counter.is_positive());

pub fn inc(&self) -> usize

Increments the counter by one and returns the new value.

Returns

The counter value after the increment.

Panics

Panics if the increment would overflow usize::MAX.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::zero();
assert_eq!(counter.inc(), 1);

pub fn add(&self, delta: usize) -> usize

Adds delta to the counter and returns the new value.

Parameters

• delta - The amount to add.

Returns

The counter value after the addition.

Panics

Panics if the addition would overflow usize::MAX.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(2);
assert_eq!(counter.add(3), 5);

pub fn try_add(&self, delta: usize) -> Option<usize>

Tries to add delta to the counter.

Parameters

• delta - The amount to add.

Returns

Some(new_value) if the addition succeeds, or None if it would overflow usize::MAX. On None, the counter is left unchanged.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(2);
assert_eq!(counter.try_add(3), Some(5));

pub fn dec(&self) -> usize

Decrements the counter by one and returns the new value.

This method is useful for detecting the transition to zero:

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(1);
if counter.dec() == 0 {
    // This call consumed the final counted item.
}

Returns

The counter value after the decrement.

Panics

Panics if the current value is zero.

pub fn try_dec(&self) -> Option<usize>

Tries to decrement the counter by one.

Returns

Some(new_value) if the decrement succeeds, or None if the current value is zero. On None, the counter is left unchanged.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(1);
assert_eq!(counter.try_dec(), Some(0));
assert_eq!(counter.try_dec(), None);

pub fn sub(&self, delta: usize) -> usize

Subtracts delta from the counter and returns the new value.

Parameters

• delta - The amount to subtract.

Returns

The counter value after the subtraction.

Panics

Panics if the subtraction would make the counter negative.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(5);
assert_eq!(counter.sub(2), 3);

pub fn try_sub(&self, delta: usize) -> Option<usize>

Tries to subtract delta from the counter.

Parameters

• delta - The amount to subtract.

Returns

Some(new_value) if the subtraction succeeds, or None if it would make the counter negative. On None, the counter is left unchanged.

Example

use qubit_atomic::AtomicCount;

let counter = AtomicCount::new(3);
assert_eq!(counter.try_sub(2), Some(1));
assert_eq!(counter.try_sub(2), None);

Trait Implementations

impl Debug for AtomicCount

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

Formats the current counter value for debugging.

Parameters

• f - The formatter receiving the debug representation.

Returns

A formatting result from the formatter.

impl Default for AtomicCount

fn default() -> Self

Creates a zero-valued atomic counter.

Returns

A counter whose current value is zero.

impl Display for AtomicCount

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

Formats the current counter value with decimal display formatting.

Parameters

• f - The formatter receiving the displayed value.

Returns

A formatting result from the formatter.

impl From<AtomicCount> for ArcAtomicCount

fn from(counter: AtomicCount) -> Self

Converts an atomic counter into a shared atomic counter wrapper.

Parameters

• counter - The counter container to share.

Returns

A shared counter wrapper owning counter.

impl From<usize> for AtomicCount

fn from(value: usize) -> Self

Converts an initial counter value into an AtomicCount.

Parameters

• value - The initial counter value.

Returns

A counter initialized to value.