AtomicInt64

AtomicInt64

AtomicInt64(initial_value: int = 0)

Bases: int

An int that may be updated atomically.

Warning

AtomicInt64 is bound to 64-bit signed integers: each of its methods may raise OverflowError.

AtomicInt64 borrows part of its API from Java's AtomicInteger, so that it should feel familiar to use, if you're coming to Python from Java. It also implements most numeric magic methods, so that it should feel comfortable to use for Pythonistas.

Note

The hash of an AtomicInt64 is independent of its value. Two AtomicInt64s may have the same hash, but hold different values. They may also have different hashes, but hold the same values.

If you need to get the hash of the currently stored int value, you should do this:

hash(my_atomic_int.get())

An AtomicInt64 and all of its associated AtomicInt64Handles share the same hash value.

Note

The following operations are supported by int, but not AtomicInt64:

• __itruediv__ (e.g. my_atomic_int /= 3.14 — an AtomicInt64 cannot be used to store floats)
• as_integer_ratio
• bit_length
• conjugate
• from_bytes
• to_bytes
• denominator
• numerator
• imag
• real

You can of course call get on AtomicInt64 and then call the desired method on the standard int object.

Methods:

• compare_and_set –

  Atomically read the current value of this AtomicInt64:

• get –

  Atomically read the current value of this AtomicInt64.

• set –

  Unconditionally set the value of this AtomicInt64 to desired.

• get_and_set –

  Atomically swap the value of this AtomicInt64 to desired and return

• increment_and_get –

  Atomically increment this AtomicInt64 by amount and return the

• get_and_increment –

  Like increment_and_get, but returns the

• decrement_and_get –

  Atomically decrement this AtomicInt64 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 AtomicInt64 by applying

• get_and_update –

  Like update_and_get, but returns the

• get_handle –

  Get a thread-local handle for this AtomicInt64.

compare_and_set

compare_and_set(expected: int, desired: int) -> bool

Atomically read the current value of this AtomicInt64:

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

get

get() -> int

Atomically read the current value of this AtomicInt64.

set

set(desired: int) -> None

Unconditionally set the value of this AtomicInt64 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 AtomicInt64.

get_and_set

get_and_set(desired: int) -> int

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

increment_and_get

increment_and_get(amount: int = 1) -> int

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

get_and_increment

get_and_increment(amount: int = 1) -> int

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

decrement_and_get

decrement_and_get(amount: int = 1) -> int

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

get_and_decrement

get_and_decrement(amount: int = 1) -> int

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

update_and_get

update_and_get(callable: Callable[[int], int]) -> int

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

callable should be a function that takes one int parameter and returns an int.

Warning

The callable 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.

get_and_update

get_and_update(callable: Callable[[int], int]) -> int

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 AtomicInt64.

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

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