atomic-dict

library0.5.0pypypi✓ verified 84d ago

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.

database serialization

pip install atomic-dict

github ↗package ↗

INSTALL

IMPORT

SIG · ATOMIC-DICT

atomic-dict

databasepythonv0.5.0

Install

1.8s avg

Import

—

Disk

15MB

Pass rate

2/ 10

Env Coverage2 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 1.9s

py 3.11

✕ build_error

py 3.12

✕ build_error

py 3.13

✕ build_error

✓ 1.6s

py 3.9

✕ build_error

15MB installed

● package 15MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AtomicDict

✓ from atomic_dict import AtomicDict

✗ from atomic-dict import AtomicDict

Hyphen not valid in Python identifiers, use underscore.

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

Debug

Known issues

gotchaAtomicDict 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.

affects: all

gotchaCreating 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).

affects: all

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

fix

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

affects: >=0.3.0

Errors

Common errors & fixes

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

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'.

PermissionError: [Errno 1] Operation not permitted

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'.

TypeError: only integer values are allowed

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

fix

Convert values to 64-bit integers before assignment.

Upgrade

Version history

0.5.0latest on PyPI · released Aug 17, 2024

Audit

Dependencies

typing_extensionsrequiredUsed for type hinting Self type

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/terpstra/atomic-dict ↗

packagehttps://pypi.org/project/atomic-dict/ ↗