Skip to content

AtomicInt64

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.

__init__(initial_value=0)

compare_and_set(expected, desired)

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()

Atomically read the current value of this AtomicInt64.

set(desired)

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(desired)

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

increment_and_get(amount=1)

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

get_and_increment(amount=1)

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

decrement_and_get(amount=1)

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

get_and_decrement(amount=1)

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

update_and_get(callable)

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(callable)

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

get_handle()

Get a thread-local handle for this AtomicInt64.

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

AtomicInt64Handle

Bases: AtomicInt64

A thread-local handle for an AtomicInt64. It behaves exactly like AtomicInt64, but provides some performance benefits.

You cannot instantiate an AtomicInt64Handle directly. Create it by calling AtomicInt64.get_handle: 

my_handle = my_atomic_int.get_handle()