| Name | pyatomix JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | None |
| Summary | Cross platform atomic int for Python |
| upload_time | 2025-02-01 05:09:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | BSD |
| keywords |
atomic
atomics
free-threading
no-gil
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## pyatomix provides a 64 bit AtomicInt class for Python
I'm pretty sure this is the only atomics library that works with Python 3.13 free-threaded.
Windows users will need to have Visual Studio installed to build this.
It uses Pybind11 and pip/setuptools will build it automatically. It's been tested on Windows and Linux.
Under the hood it uses MSVC/GCC instrinsics or falls back to std::atomic.
Linux users will need the Python dev package installed for their Python version to install atomix, for instance: python3.13-dev
## Installation
```
pip install -U pyatomix
-or-
git clone https://github.com/0xDEADFED5/pyatomix.git
pip install -U ./pyatomix
```
## Usage
```python
from pyatomix import AtomicInt
x = AtomicInt(7) # initial value of 7
x += 1 # or
x.increment() # both are equivalent
```
all the math operators except /= are supported, so you can add/subtract/etc. and they'll be atomic.
# Performance
Depending on compiler and OS, AtomicInt increment is 4-5x slower than a standard increment, which is still pretty fast.
1 million atomic increments in a for loop takes me 160ms in Linux, while incrementing a regular int 1 million times takes 40ms.
On linux the GCC intrinsics were really close to std::atomics performance. Intrinsics are a tiny bit faster than std::atomics on Windows.
If someone wants to create a PR for ARM intrinsics I'll add them, but I doubt there's much point.
# Note
If you use this in free-threaded Python, you will get this message:
RuntimeWarning: The global interpreter lock (GIL) has been enabled to load module 'atomix_base', which has not declared that it can run safely without the GIL. To override this behavior and keep the GIL disabled (at your own risk), run with PYTHON_GIL=0 or -Xgil=0.
I'm not sure what I need to add to this package to fix it, so in the meantime you can set the PYTHON_GIL environment variable.
Set it from powershell with this command: `$env:PYTHON_GIL = "0"`
compare_exchange_weak is unavailable in MSVC instrinsics, so if you want it in Windows you should uncomment the lines in main.cpp to force USE_ATOMIC
# To run the tests
```python
from pyatomix import AtomicTest
x = AtomicTest()
x.run()
```
# API list, all these are atomic
```python
AtomicInt.increment() : same as += 1
AtomicInt.decrement() : same as -= 1
AtomicInt.store(value) : assign value, doesn't return anything
AtomicInt.load() : read value
AtomicInt.add(value) : same as += value
AtomicInt.subtract(value) : same as -= value
AtomicInt.exchange(value) : assign value. returns previous value
AtomicInt.compare_exchange(expected, value) : if current value == expected, replace it with value. returns True on success
AtomicInt.compare_exchange_weak(expected, value) : same as above, but use weak API if available.
```
# Overloaded operator list
`==,!=,-,~,+,+=,-=,*,*=,/,//,//=,|,|=,%,%=,**,**=,&,&=,^,^=,>>,>>=,<<,<<=,>,>=,<,<=`
Raw data
{
"_id": null,
"home_page": null,
"name": "pyatomix",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "0xDEADFED5 <admin@terminoid.com>",
"keywords": "atomic, atomics, free-threading, no-GIL",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5b/5a/eebf55f2b17588694ac1f554aff5f0f428729d8add3cb4c41e9527f86c6e/pyatomix-0.0.4.tar.gz",
"platform": null,
"description": "## pyatomix provides a 64 bit AtomicInt class for Python\r\n\r\nI'm pretty sure this is the only atomics library that works with Python 3.13 free-threaded.\r\nWindows users will need to have Visual Studio installed to build this.\r\nIt uses Pybind11 and pip/setuptools will build it automatically. It's been tested on Windows and Linux.\r\n\r\nUnder the hood it uses MSVC/GCC instrinsics or falls back to std::atomic.\r\nLinux users will need the Python dev package installed for their Python version to install atomix, for instance: python3.13-dev\r\n\r\n## Installation\r\n\r\n```\r\npip install -U pyatomix\r\n-or-\r\ngit clone https://github.com/0xDEADFED5/pyatomix.git\r\npip install -U ./pyatomix\r\n```\r\n\r\n## Usage\r\n\r\n```python\r\nfrom pyatomix import AtomicInt\r\nx = AtomicInt(7) # initial value of 7\r\nx += 1 # or\r\nx.increment() # both are equivalent\r\n```\r\n\r\nall the math operators except /= are supported, so you can add/subtract/etc. and they'll be atomic.\r\n\r\n\r\n# Performance\r\n\r\nDepending on compiler and OS, AtomicInt increment is 4-5x slower than a standard increment, which is still pretty fast.\r\n1 million atomic increments in a for loop takes me 160ms in Linux, while incrementing a regular int 1 million times takes 40ms.\r\nOn linux the GCC intrinsics were really close to std::atomics performance. Intrinsics are a tiny bit faster than std::atomics on Windows.\r\nIf someone wants to create a PR for ARM intrinsics I'll add them, but I doubt there's much point.\r\n\r\n# Note\r\n\r\nIf you use this in free-threaded Python, you will get this message:\r\n\r\nRuntimeWarning: The global interpreter lock (GIL) has been enabled to load module 'atomix_base', which has not declared that it can run safely without the GIL. To override this behavior and keep the GIL disabled (at your own risk), run with PYTHON_GIL=0 or -Xgil=0.\r\n\r\nI'm not sure what I need to add to this package to fix it, so in the meantime you can set the PYTHON_GIL environment variable.\r\nSet it from powershell with this command: `$env:PYTHON_GIL = \"0\"`\r\n\r\ncompare_exchange_weak is unavailable in MSVC instrinsics, so if you want it in Windows you should uncomment the lines in main.cpp to force USE_ATOMIC\r\n\r\n# To run the tests\r\n\r\n```python\r\nfrom pyatomix import AtomicTest\r\nx = AtomicTest()\r\nx.run()\r\n```\r\n\r\n# API list, all these are atomic\r\n\r\n```python\r\nAtomicInt.increment() : same as += 1\r\nAtomicInt.decrement() : same as -= 1\r\nAtomicInt.store(value) : assign value, doesn't return anything\r\nAtomicInt.load() : read value\r\nAtomicInt.add(value) : same as += value\r\nAtomicInt.subtract(value) : same as -= value\r\nAtomicInt.exchange(value) : assign value. returns previous value\r\nAtomicInt.compare_exchange(expected, value) : if current value == expected, replace it with value. returns True on success\r\nAtomicInt.compare_exchange_weak(expected, value) : same as above, but use weak API if available.\r\n```\r\n\r\n# Overloaded operator list\r\n\r\n`==,!=,-,~,+,+=,-=,*,*=,/,//,//=,|,|=,%,%=,**,**=,&,&=,^,^=,>>,>>=,<<,<<=,>,>=,<,<=`\r\n\r\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Cross platform atomic int for Python",
"version": "0.0.4",
"project_urls": {
"Github": "https://github.com/0xDEADFED5/pyatomix",
"Homepage": "https://github.com/0xDEADFED5/pyatomix"
},
"split_keywords": [
"atomic",
" atomics",
" free-threading",
" no-gil"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e1b62325f1d03a4b09ed68c1aeba6ce3d38ad375ea130ba58342e4a48422f6c1",
"md5": "3cdf8b595c330f3bef0af618c7b57546",
"sha256": "dfd494128738def96526e3baad096b9f5523dfac8e1a2d4cefbb614e051ba586"
},
"downloads": -1,
"filename": "pyatomix-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3cdf8b595c330f3bef0af618c7b57546",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5070,
"upload_time": "2025-02-01T05:09:42",
"upload_time_iso_8601": "2025-02-01T05:09:42.247155Z",
"url": "https://files.pythonhosted.org/packages/e1/b6/2325f1d03a4b09ed68c1aeba6ce3d38ad375ea130ba58342e4a48422f6c1/pyatomix-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b5aeebf55f2b17588694ac1f554aff5f0f428729d8add3cb4c41e9527f86c6e",
"md5": "11b62677b2445ded9d7621da4df7e379",
"sha256": "016a68d757d72433561692d123c65d8da4f73932af5889f0a9f7f249a7247a0c"
},
"downloads": -1,
"filename": "pyatomix-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "11b62677b2445ded9d7621da4df7e379",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5189,
"upload_time": "2025-02-01T05:09:43",
"upload_time_iso_8601": "2025-02-01T05:09:43.530113Z",
"url": "https://files.pythonhosted.org/packages/5b/5a/eebf55f2b17588694ac1f554aff5f0f428729d8add3cb4c41e9527f86c6e/pyatomix-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-01 05:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "0xDEADFED5",
"github_project": "pyatomix",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyatomix"
}
