easy-to-use lock-free atomic integers, booleans, and floats for Python
Project description
atomicx
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 Ruststd::sync::atomic
module. - The floating point atomic operations are delegated to the
portable-atomic
crate.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6547ee28c3adf35e3a7f57537f98c61d205f96059b8f615b749126dbe226cb40 |
|
MD5 | 4800b7b60a1a0d9b79d5313c958f99e1 |
|
BLAKE2b-256 | 6201c3063ca317653707e207abee494344c58d5e159e06eb8a749cf630eec53c |
File details
Details for the file atomicx-0.0.14-cp37-abi3-win_amd64.whl
.
File metadata
- Download URL: atomicx-0.0.14-cp37-abi3-win_amd64.whl
- Upload date:
- Size: 158.5 kB
- Tags: CPython 3.7+, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.7.4
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ef8ca445ed816caf1c0193b4e6ede41d0345958be57626039ffa7be9e73cd17b |
|
MD5 | f08ab48b58e6a1f9717347fe1fb7e676 |
|
BLAKE2b-256 | 8188632d6f23ce1e30406f0c28ab859c4b909ea566ed92a3e30c12fba23f9ec7 |
File details
Details for the file atomicx-0.0.14-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: atomicx-0.0.14-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 291.6 kB
- Tags: CPython 3.7+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.7.4
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 87b647df0b4cf997153639a61980a91010a629bc7c036f0bc8918ea6187a3cce |
|
MD5 | f450cdfd5b70b87ed70d6d142176dc37 |
|
BLAKE2b-256 | bbab6228b5dac380ca5475050023011a10819d69d06040c2d54ebabbdf89653b |
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
- Download URL: atomicx-0.0.14-cp37-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
- Upload date:
- Size: 506.1 kB
- Tags: CPython 3.7+, macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.7.4
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 97006cfb7203a4af059f831714986ea30509b1263f5b6c93fa467c60111fa2b6 |
|
MD5 | e3c8a90584aed2f85afc22388e76b390 |
|
BLAKE2b-256 | 158e52379d881c198dc6602d5dad771dc89294790a3233951c838e5885ce6597 |