atomic-dict

0.5.0 verified Fri May 01 auth: no python

A lock-free shared memory dictionary for 64-bit integer keys and values, built on atomic operations. Version 0.5.0 supports Python >=3.10. Frequently updated with minor releases.

pip install atomic-dict

Common errors

error AttributeError: module 'atomic_dict' has no attribute 'AtomicDict' ↓

cause Trying to import via 'import atomic_dict' and then using 'atomic_dict.AtomicDict' but possibly package name inconsistency.

fix

Use 'from atomic_dict import AtomicDict'.

error PermissionError: [Errno 1] Operation not permitted ↓

cause The library uses shared memory (mmap with MAP_SHARED) which may require elevated privileges on Linux.

fix

Run as root or increase memlock limit via 'ulimit -l unlimited'.

error TypeError: only integer values are allowed ↓

cause Attempting to store a non-integer value (e.g., float or string) in the dictionary.

fix

Convert values to 64-bit integers before assignment.

Warnings

gotcha AtomicDict only supports integer keys and values (64-bit). Passing floats, strings, or other types will raise an error or have undefined behavior. ↓

fix Ensure keys and values are within -2^63 to 2^63-1.

gotcha Creating an AtomicDict may require root/admin privileges on some operating systems (e.g., Linux CAP_IPC_LOCK or Windows SeLockMemoryPrivilege). On systems without privileges, initialization may fail with permission errors. ↓

fix Run with appropriate privileges or configure system limits (e.g., increase memlock on Linux).

deprecated The function 'reset()' was renamed to 'clear()' in version 0.3.0. Using 'reset()' raises an AttributeError. ↓

fix Use 'clear()' instead of 'reset()'.

Imports

AtomicDict
wrong
```
from atomic-dict import AtomicDict
```
correct
```
from atomic_dict import AtomicDict
```
Hyphen not valid in Python identifiers, use underscore.

Quickstart

Basic usage: create an AtomicDict, set/get integer keys, and use compare_and_swap.

from atomic_dict import AtomicDict

# Create a shared memory dictionary (requires admin privileges on some systems)
d = AtomicDict()
# Set a value for integer key 42
d[42] = 12345
# Get the value
print(d[42])  # 12345
# Compare-and-swap (key 42 from 12345 to 54321)
d.compare_and_swap(42, 12345, 54321)
print(d[42])  # 54321