Struct AtomicCounter 

pub struct AtomicCounter { /* 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 AtomicUsize. 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::AtomicCounter;

let active_tasks = AtomicCounter::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 AtomicCounter

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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

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

pub fn get(&self) -> usize

Gets the current counter value.

Returns

The current counter value.

Example

use qubit_atomic::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

let counter = AtomicCounter::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::AtomicCounter;

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

Trait Implementations

impl Debug for AtomicCounter

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

Formats the value using the given formatter.

impl Default for AtomicCounter

fn default() -> Self

Returns the “default value” for a type.

impl Display for AtomicCounter

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

Formats the value using the given formatter.

impl From<usize> for AtomicCounter

fn from(value: usize) -> Self

Converts to this type from the input type.