Struct AtomicSignedCount 

pub struct AtomicSignedCount { /* 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 AtomicCount. For pure metrics or statistics, prefer the regular atomic integer types such as Atomic<isize>.

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

let backlog_delta = AtomicSignedCount::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 AtomicSignedCount

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

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

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

pub fn get(&self) -> isize

Gets the current counter value.

Returns

The current counter value.

Example

use qubit_atomic::AtomicSignedCount;

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

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

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

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

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

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

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

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

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

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

Trait Implementations

impl Debug for AtomicSignedCount

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 AtomicSignedCount

fn default() -> Self

Creates a zero-valued signed atomic counter.

Returns

A signed counter whose current value is zero.

impl Display for AtomicSignedCount

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<isize> for AtomicSignedCount

fn from(value: isize) -> Self

Converts an initial counter value into an AtomicSignedCount.

Parameters

• value - The initial counter value.

Returns

A signed counter initialized to value.