Reactive, Lock-Free Key-Value Store for Concurrent Python
Lock-free reads always, deterministic write mutexes, automatic background TTLs, reactive subscriptions, and true multi-core parallel scaling on free-threaded Python (3.13t / 3.14t).
from nimbuskv import NimbusKV
# In-memory reactive store with automatic background TTL
with NimbusKV() as store:
store.set("user:101", {"status": "active"}, ttl=60)
print(store.get("user:101"))
# Check remaining TTL deadline in seconds
print(store.ttl("user:101"))Test In-Browser Store Simulation
Verify key mutation, generational TTL deadlines, atomic compound increments, and subscription events in real-time.
Snapshot Architecture & Multi-Core Evidence
How persistent Hash Array Mapped Tries (HAMT) enable lock-free reads while deterministic write coordination eliminates CAS retry storms.
1. Readers Never Acquire Locks
Reader threads access the immutable HAMT root pointer directly. Reads never block on writers and exhibit zero latency jitter.
2. Short Write Mutex Coordination
Writes acquire a short mutex (<2µs) to construct the new HAMT root via structural sharing and atomically swap the root pointer.
3. Reactive Notification & Wakeup
Registered subscribers receive set, delete, and expire callbacks, while worker threads suspended in wait_for() wake up immediately.
Lock-Free Reads Always
State lives in an immutable persistent HAMT map. Reads simply inspect the latest snapshot with zero locks, even during intense concurrent writes.
Deterministic Write Mutex
Each write takes one brief mutex to build and publish the new snapshot. Eliminates CAS retry storms under hot-key contention.
Free-Threaded Ready
Auto-detects GIL state at import. On Python 3.13t/3.14t, concurrent reader threads achieve genuine multi-core parallel scaling.
Reactive Subscriptions
subscribe() notifies callbacks on set, delete, and expire events. wait_for() pauses threads without polling loops.
Generational TTL Compaction
v3.1.1 introduces _compact() heap maintenance, dropping stale generation entries during hot-key reschedules in O(1).
Pluggable Persistence
In-memory by default, with optional write-through SQLite or Redis mirroring. Reads never touch the backend, keeping latencies in nanoseconds.
Multi-Threaded Throughput & Latency Profile
Adopt NimbusKV for Your Specific Workload
Explore idiomatic Python code tours, verify your architecture fit, and start building with production-ready patterns.
Is NimbusKV Right for My Application?
Select what you are building and your process deployment architecture to receive an honest fit assessment, copyable code, and key trade-offs.
Recommended Approach
Use NimbusKV's immutable snapshot core with temporary cached values & session store. Readers execute lock-free in <0.65µs without contending with mutations.
- TTLs are evaluated lazily upon read and proactively swept by an internal min-heap thread.
- Heap compaction (v3.1.1) drops stale reschedule entries, but highly dynamic workloads should avoid millisecond-scale churn on millions of unique keys.
from nimbuskv import NimbusKV
import time
# Embedded, zero-overhead in-memory cache
store = NimbusKV()
# Store session with a 30-second TTL
store.set("session:token_user_42", {"uid": 42, "role": "admin"}, ttl=30)
# Instant lock-free read (<0.65µs, never blocks writers)
session = store.get("session:token_user_42")
print(f"Active user: {session['uid']}")Idiomatic Python Code Tour
Tested on Python 3.9 – 3.14tProduction Recipes
7-step quickstart & 6 production recipes for FastAPI memoization, atomic counters, and worker queues.
API Reference
Complete method signatures, parameter types, exceptions, and version-specific docstrings.
Concurrency Labs
Interactive step-by-step visualizers: race conditions, atomic coordination, and TTL timeline debugging.
Credible Signals & Continuous Verification
Transparent release metadata, verifiable CI pipelines, honest technical limitations, and continuous improvements.
NimbusKV v3.1.1— Concurrency Hardening & Memory Safety
TTL Heap Compaction (_compact)
Memory FixPeriodically rebuilds the internal min-heap to drop stale expiration deadlines from repeatedly rescheduled keys, preventing unbounded memory growth under hot keys.
Deterministic Write Mutex (<2µs hold)
ConcurrencyReplaced optimistic CAS retry loops with a single short write mutex, completely eliminating retry-storm throughput collapse under high thread contention.
ReentrantWriteError Deadlock Guard
SafetyDetects reentrant mutation calls inside atomic() or mutate() callbacks and raises immediately instead of hanging in an unrecoverable deadlock.
Permissive Apache 2.0 License
LicensingOfficially licensed under Apache 2.0 (migrated from GPLv3 in v3.1.0), enabling frictionless commercial, cloud, and proprietary enterprise adoption.
pip install --upgrade nimbuskv. Fully backwards-compatible with v3.1.0 code.Verified Runtimes & OS Platforms
Every commit runs across 6 automated GitHub Actions test matrices covering standard CPython 3.9 through 3.14t (zero-GIL) across Linux, macOS, and Windows.
Explicit Guarantees & Non-Goals
We document exact invariants: single write mutex serialization, <2µs hold times, single-process boundaries, and zero multi-process or network clustering promises.
Ready to build with lock-free concurrency?
Install NimbusKV and start leveraging reactive in-memory storage on Python 3.9 through free-threaded 3.14t.