atomicl

Yet another implementation of AtomicLong class.

Introduction

Class that allows to update long value atomically. Highly inspired by Java's AtomicLong class and atomic package. The most of performance is gained by using Cython with the pure Python fallback available.

Examples:

>> counter = atomicl.AtomicLong()
>> counter += 2
>> counter.value
2
>> counter.get_and_set(5)
2
>> counter.value
5

Supported Python Versions

atomicl currently supports CPython 3.11 through 3.14.

Development Workflow

The project uses uv for local environment management, testing, and building.

Bootstrap a development environment:

uv sync

The documented local workflow assumes the default dev group is installed via uv sync before running lint, tests, benchmarks, or packaging commands from a checkout, so Cython is available there when needed for Cython-backed packaging workflows.

Run the test suite on the default interpreter:

uv run pytest

Check lint:

uv run ruff check

Apply lint fixes and import sorting:

uv run ruff check --fix

Format code:

uv run ruff format

Run the test suite on a specific supported interpreter:

uv run --python 3.11 -m pytest
uv run --python 3.12 -m pytest
uv run --python 3.13 -m pytest
uv run --python 3.14 -m pytest

Build source and wheel distributions:

uv build

Smoke-test the benchmark entrypoint and benchmark dependencies:

uv run --group benchmark python benchmarks.py --help

Run a faster local benchmark pass for one implementation:

uv run --group benchmark python benchmarks.py --fast --impl atomicl_cy

Regenerate src/atomicl/_cy.c after editing src/atomicl/_cy.pyx:

uv sync
uv build

Build Behavior

The package keeps an optional Cython-backed extension for the fast path and retains a pure Python implementation for environments where the native extension is not installed.

Building the native extension requires a working C compiler toolchain.

To force a pure Python install from source and skip native-extension configuration entirely, set ATOMICL_NO_EXTENSIONS=1 when installing:

ATOMICL_NO_EXTENSIONS=1 pip install atomicl

Source distributions ship generated C code for the extension, so end systems installing from the released sdist do not need Cython just to build the package.

When packaging from a checkout with uv, the local build uses src/atomicl/_cy.pyx and regenerates src/atomicl/_cy.c before compiling the extension.

When ATOMICL_NO_EXTENSIONS=1 is set, packaging skips configuring the extension and installs the pure Python implementation directly.

When Cython is not available, the build falls back to src/atomicl/_cy.c. If the extension build fails, installation fails; set ATOMICL_NO_EXTENSIONS=1 to force a pure Python install.

Differences from atomic

atomic is a more mature library and is battle-tested.

Despite small API differences, the huge difference between atomic and atomicl is comparisons operations support. atomicl does not supports comparison and, for now, I do not see reasons to have it. I tend to agree with folks from java on this topic.

atomic is backed by CFFI which makes it a good choice for CPython and PyPy. atomicl with Cython extension gains better performance on CPython and performs worse on PyPy. See Benchmarks for more details.

Benchmarks

Run benchmarks.py to compare the pure Python and Cython-backed implementations on your current machine.

License

MIT