AtomicNumber

AtomicNumber

Bases: AtomicRef

A numeric value that may be updated atomically.

AtomicNumber can hold Python integers, floats, complex numbers, and other numeric objects such as Decimal and Fraction. Supported operations depend on the stored type.

Basic Usage

from cereggii import AtomicNumber

number = AtomicNumber(1)

# Use it like a regular number
number += 1
another = number * 2

# Use the AtomicNumber API
number.increment_and_get()
number.compare_and_set(2, 2.5)

Note

The hash is based on object identity, not the stored value. Two AtomicNumber objects that compare equal can have different hashes. Use hash(number.get()) to hash the current value.

Note

Each read or update is atomic. However, an operation involving two distinct AtomicNumber objects (e.g. AtomicNumber(a) + AtomicNumber(b)) reads them separately and doesn't provide a simultaneous snapshot of their values.

When the same object occurs on both sides (e.g. AtomicNumber(a) + AtomicNumber(a)), that operation reuses one read of its value.

Methods:

• __init__ –
• compare_and_set –

  Atomically read the current value of this AtomicNumber:

• get –

  Atomically read the current value of this AtomicRef.

• set –

  Unconditionally set the value of this AtomicRef to desired.

• get_and_set –

  Atomically swap the value of this AtomicRef to desired and return

• increment_and_get –

  Atomically increment this AtomicNumber by amount and return the

• get_and_increment –

  Like increment_and_get, but returns the

• decrement_and_get –

  Atomically decrement this AtomicNumber by amount and return the

• get_and_decrement –

  Like decrement_and_get, but returns the

• update_and_get –

  Atomically update the value currently stored in this AtomicNumber by applying

• get_and_update –

  Like update_and_get, but returns the

• get_handle –

  Get a thread-local handle for this AtomicRef.

__init__

__init__(initial_value: Any = 0)

compare_and_set

compare_and_set(expected, desired)

Atomically read the current value of this AtomicNumber:

• if it is expected, then replace it with desired and return True
• else, don't change it and return False.

get

get() -> T

Atomically read the current value of this AtomicRef.

set

set(desired: T)

Unconditionally set the value of this AtomicRef to desired.

Warning

Use compare_and_set instead.

When using this method, it is not possible to know that the value currently stored is the one being expected -- it may be mutated by another thread before this mutation is applied. Use this method only when no other thread may be writing to this AtomicRef.

get_and_set

get_and_set(desired: T) -> T

Atomically swap the value of this AtomicRef to desired and return the previously stored value.

increment_and_get

increment_and_get(amount=1)

Atomically increment this AtomicNumber by amount and return the incremented value.

get_and_increment

get_and_increment(amount=1)

Like increment_and_get, but returns the value that was stored before applying this operation.

decrement_and_get

decrement_and_get(amount=1)

Atomically decrement this AtomicNumber by amount and return the decremented value.

get_and_decrement

get_and_decrement(amount=1)

Like decrement_and_get, but returns the value that was stored before applying this operation.

update_and_get

update_and_get(update)

Atomically update the value currently stored in this AtomicNumber by applying update and return the updated value.

update should be a function that takes the current numeric value and returns a new numeric value.

Warning

The update function must be stateless: it will be called at least once but there is no upper bound to the number of times it will be called within one invocation of this method.

If the stored value is mutable, update must not mutate it in place.

get_and_update

get_and_update(update)

Like update_and_get, but returns the value that was stored before applying this operation.

get_handle

get_handle() -> ThreadHandle[Self]

Get a thread-local handle for this AtomicRef.

When using a thread-local handle, you can improve the performance of your application.

See ThreadHandle for more information on thread-local object handles.