---
id: atomic-dict
version: "0.5.0"
license: BSD-3
license_treatment: permissive
maintenance: dormant
---

# atomic_dict — A library for lock-free shared 64-bit dictionaries

License: permissive · Maintenance: dormant · Downloads: 266.0K/mo

## What it is and what it does

Atomic-Dict is a specialized synchronization primitive for multiprocess Python programs that need to share and atomically update 64-bit integer values across process boundaries. It implements a fixed-size Map[Int, Int] with lock-free operations—no mutexes, no waits—using cache-local memory layout for speed. The library is deliberately minimal: keys and values are 64-bit integers only, keys cannot be deleted once allocated, and the dictionary size is fixed at creation. It is not a general-purpose dictionary but rather a building block for inter-process coordination in performance-critical code.

The package supports atomic operations including compare-and-swap, exchange, increment, decrement, bitwise OR/XOR/AND, and swap. To work with complex types, you pre-allocate a shared list before forking and use list indices as keys and values. The design trades flexibility for speed and simplicity—operations never block, making it suitable for tight loops in worker processes that need to coordinate counters, flags, or indices without contention.

Use it for:

- Coordinate counters across worker processes in a multiprocessing pool without locks or synchronization overhead.
- Implement lock-free work-stealing or load-balancing primitives where processes update shared state atomically.
- Build inter-process synchronization for real-time systems where latency and cache locality matter more than feature richness.
- Share and update indexed references to complex objects across processes by using the dictionary as a pointer map.
- Implement fast, contention-free metrics or telemetry collection in parallel workloads.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Atomic-Dict provides a lock-free, shared 64-bit integer key-value map for multiprocess synchronization using atomic operations like compare-and-swap, exchange, and increment.

Yes, if you need lock-free inter-process integer coordination in Python and accept the constraints: fork-based multiprocessing, fixed-size dictionary, 64-bit integers only, and manylinux_2_28 x86_64 platform dependency. The dormant maintenance status and zero community stars suggest limited adoption; verify it fits your exact use case before committing. Not suitable for general-purpose shared data structures or non-fork multiprocessing contexts.

## Install

pip install atomic-dict
uv add atomic-dict
poetry add atomic-dict

## Installing atomic_dict

Before you install: Medium install friction due to platform-specific wheels (manylinux_2_28 x86_64 only for Python 3.10–3.14). Repository is dormant (last commit 2024-08-17, no stars), suggesting limited ongoing maintenance or community adoption.

License in practice: BSD-3 permissive license allows commercial and private use with minimal restrictions; attribution required.

Quickstart:

from atomic_dict import AtomicDict
import multiprocessing

dict = AtomicDict(1024*1024)
context = multiprocessing.get_context("fork")
def worker(id: int) -> None:
    dict[1].add(1)  # atomic increment
    dict[100 + id] = id
with context.Pool(8) as p:
    p.map(worker, range(16))

Requires fork-based multiprocessing context; keys must be non-zero 64-bit integers; maximum dictionary size must be specified upfront.

Verify before relying:

- Whether the manylinux_2_28 wheel constraint limits deployment to recent Linux distributions or if other platforms are supported.
- Whether the 0 stars and dormant status reflect low adoption or simply a niche use case with satisfied users.

## Package facts

- License: BSD-3 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: dormant
- Downloads: 266.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lock-free shared dictionary, atomic operations multiprocessing, 64-bit integer map, compare-and-swap synchronization, shared memory dictionary, multiprocess atomic updates, cache-local synchronization primitive, lock-free, multiprocessing, synchronization-primitive

[View on SkillFed](https://skillfed.io/packages/atomic-dict) · [View on PyPI](https://pypi.org/project/atomic-dict/)