Struct AtomicSignedCounter 

pub struct AtomicSignedCounter { /* private fields */ }

A signed atomic counter with synchronization-oriented operations.

Use this type when the counter models a delta, balance, backlog, offset, or other quantity that may legitimately cross zero. Examples include producer minus consumer deltas, permit debt, retry backlog changes, or accumulated scheduling offsets.

For counters that must never be negative, prefer AtomicCounter. For pure metrics or statistics, prefer the regular atomic integer types such as AtomicIsize.

This counter never wraps. Operations that would overflow the signed range panic. Use try_add or try_sub when overflow is a normal business outcome.

Example

use qubit_atomic::AtomicSignedCounter;

let backlog_delta = AtomicSignedCounter::zero();

assert_eq!(backlog_delta.add(5), 5);
assert_eq!(backlog_delta.sub(8), -3);
assert!(backlog_delta.is_negative());

Author

Haixing Hu

Implementations

impl AtomicSignedCounter

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

Creates a new signed atomic counter.

Parameters

• value - The initial counter value.

Returns

A signed counter initialized to value.

Example

use qubit_atomic::AtomicSignedCounter;

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

pub const fn zero() -> Self

Creates a new signed counter initialized to zero.

Returns

A signed counter whose current value is zero.

Example

use qubit_atomic::AtomicSignedCounter;

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

pub fn get(&self) -> isize

Gets the current counter value.

Returns

The current counter value.

Example

use qubit_atomic::AtomicSignedCounter;

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

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

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

pub fn is_negative(&self) -> bool

Returns whether the current counter value is less than zero.

Returns

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

Example

use qubit_atomic::AtomicSignedCounter;

let counter = AtomicSignedCounter::new(-1);
assert!(counter.is_negative());

pub fn inc(&self) -> isize

Increments the counter by one and returns the new value.

Returns

The counter value after the increment.

Panics

Panics if the increment would overflow isize::MAX.

Example

use qubit_atomic::AtomicSignedCounter;

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

pub fn dec(&self) -> isize

Decrements the counter by one and returns the new value.

Returns

The counter value after the decrement.

Panics

Panics if the decrement would underflow isize::MIN.

Example

use qubit_atomic::AtomicSignedCounter;

let counter = AtomicSignedCounter::zero();
assert_eq!(counter.dec(), -1);

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

Adds delta to the counter and returns the new value.

Parameters

• delta - The amount to add. It may be negative.

Returns

The counter value after the addition.

Panics

Panics if the addition would overflow or underflow the signed range.

Example

use qubit_atomic::AtomicSignedCounter;

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

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

Tries to add delta to the counter.

Parameters

• delta - The amount to add. It may be negative.

Returns

Some(new_value) if the addition succeeds, or None if it would overflow or underflow the signed range. On None, the counter is left unchanged.

Example

use qubit_atomic::AtomicSignedCounter;

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

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

Subtracts delta from the counter and returns the new value.

Parameters

• delta - The amount to subtract. It may be negative.

Returns

The counter value after the subtraction.

Panics

Panics if the subtraction would overflow or underflow the signed range.

Example

use qubit_atomic::AtomicSignedCounter;

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

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

Tries to subtract delta from the counter.

Parameters

• delta - The amount to subtract. It may be negative.

Returns

Some(new_value) if the subtraction succeeds, or None if it would overflow or underflow the signed range. On None, the counter is left unchanged.

Example

use qubit_atomic::AtomicSignedCounter;

let counter = AtomicSignedCounter::new(2);
assert_eq!(counter.try_sub(5), Some(-3));

Trait Implementations

impl Debug for AtomicSignedCounter

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

Formats the value using the given formatter.

impl Default for AtomicSignedCounter

fn default() -> Self

Returns the “default value” for a type.

impl Display for AtomicSignedCounter

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

Formats the value using the given formatter.

impl From<isize> for AtomicSignedCounter

fn from(value: isize) -> Self

Converts to this type from the input type.