Skip to main content

easy-to-use lock-free atomic integers, booleans, and floats for Python

Project description

atomicx

PyPI version

atomicx is an easy-to-use atomics library for Python, providing atomic integer, boolean, and floats. It allows you to perform atomic operations on shared variables, ensuring thread-safety and preventing race conditions in concurrent programming. Everything is entirely lock-free and is backed by Rust's atomic types (or from portable-atomic).

Features

  • Atomic integer operations: load, store, add, subtract, swap, compare and exchange, multiply, divide, increment, decrement.
  • Atomic boolean operations: load, store, swap, compare and exchange, flip.
  • Atomic floats: load, store, swap, compare and exchange.
  • Strong typing provided as stubs for static type checkers.

Installation

Binary wheels are provided for Python 3.7 and above on Linux, macOS, and Windows:

pip install atomicx

Usage

See the documentation for more information. Here's a quick overview:

Atomic Integer

from atomicx import AtomicInt

# Create an atomic integer with an initial value of 0
atom = AtomicInt()

# Perform atomic operations
atom.store(10)
value = atom.load()
print(f"Value: {value}")

previous_value = atom.swap(20)
print(f"Previous Value: {previous_value}")

atom.add(5)
print(f"Result after addition: {atom}")

# Increment and decrement operations
atom.inc()
atom.dec()

Atomic Boolean

from atomicx import AtomicBool

# Create an atomic boolean with an initial value of False
atom = AtomicBool()

# Perform atomic operations
atom.store(True)
value = atom.load()
print(f"Value: {value}")

previous_value = atom.swap(False)
print(f"Previous Value: {previous_value}")

result = atom.compare_exchange(False, True)
print(f"Swap Result: {result}")

# Flip the value of the atomic boolean
atom.flip()

Atomic Float

from atomicx import AtomicFloat

# Create an atomic float with an initial value of 0.0
atom = AtomicFloat()
print(f"Initial Value: {atom.load()}")

# Perform atomic operations
atom.store(3.14)
value = atom.load()
print(f"Value: {value}")

# See docs for more operations

Thread Safety

Atomic variables are thread-safe and can be shared between threads. Each predefined operation on them are executed per thread as an indivisible unit. Here's an example of using an atomic integer in a multithreaded environment:

import threading
from atomicx import AtomicInt

x = AtomicInt(0)
def increment():
    for _ in range(1000):
        x.inc() # equivalent to x.add(1) or x += 1

threads = []
for _ in range(10):
    thread = threading.Thread(target=increment)
    thread.start()
    threads.append(thread)

for thread in threads:
    thread.join()

assert x.load() == 1000 * 10

The equivalent in vanilla Python without locks is not thread-safe in general.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

  • The atomicx library is heavily dependent on and inspired by the Rust std::sync::atomic module.
  • The floating point atomic operations are delegated to the portable-atomic crate.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

atomicx-0.0.14.tar.gz (13.3 kB view details)

Uploaded Source

Built Distributions

atomicx-0.0.14-cp37-abi3-win_amd64.whl (158.5 kB view details)

Uploaded CPython 3.7+ Windows x86-64

atomicx-0.0.14-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (291.6 kB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ x86-64

atomicx-0.0.14-cp37-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (506.1 kB view details)

Uploaded CPython 3.7+ macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64

File details

Details for the file atomicx-0.0.14.tar.gz.

File metadata

  • Download URL: atomicx-0.0.14.tar.gz
  • Upload date:
  • Size: 13.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: maturin/1.7.4

File hashes

Hashes for atomicx-0.0.14.tar.gz
Algorithm Hash digest
SHA256 6547ee28c3adf35e3a7f57537f98c61d205f96059b8f615b749126dbe226cb40
MD5 4800b7b60a1a0d9b79d5313c958f99e1
BLAKE2b-256 6201c3063ca317653707e207abee494344c58d5e159e06eb8a749cf630eec53c

See more details on using hashes here.

Provenance

File details

Details for the file atomicx-0.0.14-cp37-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for atomicx-0.0.14-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ef8ca445ed816caf1c0193b4e6ede41d0345958be57626039ffa7be9e73cd17b
MD5 f08ab48b58e6a1f9717347fe1fb7e676
BLAKE2b-256 8188632d6f23ce1e30406f0c28ab859c4b909ea566ed92a3e30c12fba23f9ec7

See more details on using hashes here.

Provenance

File details

Details for the file atomicx-0.0.14-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for atomicx-0.0.14-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 87b647df0b4cf997153639a61980a91010a629bc7c036f0bc8918ea6187a3cce
MD5 f450cdfd5b70b87ed70d6d142176dc37
BLAKE2b-256 bbab6228b5dac380ca5475050023011a10819d69d06040c2d54ebabbdf89653b

See more details on using hashes here.

Provenance

File details

Details for the file atomicx-0.0.14-cp37-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for atomicx-0.0.14-cp37-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 97006cfb7203a4af059f831714986ea30509b1263f5b6c93fa467c60111fa2b6
MD5 e3c8a90584aed2f85afc22388e76b390
BLAKE2b-256 158e52379d881c198dc6602d5dad771dc89294790a3233951c838e5885ce6597

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page