NimbusKV Technical Transparency Center

Clear specifications of NimbusKV's concurrency guarantees, memory model, lock architecture, error semantics, and explicit non-goals.

Lock-Free Reads (Readers Never Lock)

Guarantee

Readers never acquire a lock, wait on a mutex, or retry an atomic compare-and-swap loop. When a thread calls store.get(), store.items(), or reads a snapshot, it reads directly from an immutable Hash Array Mapped Trie (HAMT) node pointer.

Read Complexity: O(1) · Lock Contention: Zero

Single Short Write Mutex

v3 Architecture

All writes (set(), delete(), mset(), atomic()) serialize through a single short, deterministic mutex. Writers take the lock once, perform path-copying on the HAMT, swap the root pointer, and release the lock immediately.

Hold Time: < 2μs · Lost Updates: Impossible

ReentrantWriteError Specification

Deadlock Safety

Calling a write method (like store.set() or store.delete()) from inside an atomic() or mutate() callback raises ReentrantWriteError immediately. This prevents recursive lock acquisition and deadlocks.

raise ReentrantWriteError("Nested write prohibited")

Generational TTL Memory Safety

Zero Leak

In v3.1.0, the TTL scheduler tracks generation counters. Overwriting a key increments its generation, so stale priority queue deadlines are safely discarded upon inspection without memory leaks.

Reclamation: Active on heap tick · Memory: O(pending TTLs)

Explicit Architectural Boundaries & Non-Goals

1. In-Process Only

NimbusKV is an in-process Python data structure. Separate OS processes or machines do NOT automatically share memory without a network layer.

2. Not a Distributed Clustered DB

NimbusKV is not an alternative to distributed multi-node Redis clusters. It is optimized for sub-microsecond local in-memory thread concurrency.

3. Deterministic Persistence

SQLite and Redis persistence backends operate as write-ahead or write-behind layers under the write lock, designed for local durability.

Responsible Security Disclosure Policy

We follow strict coordinated vulnerability disclosure. Discovered issues receive priority patches and CVE tracking.

View Security Policy