KeyDB Overview: Multithreaded Architecture, Thread Model, Fastlock, and Active‑Replica

KeyDB is a high‑performance branch of Redis that focuses on multithreading, memory efficiency, and high throughput, while preserving full compatibility with the Redis protocol, modules, and scripting, including atomic guarantees for scripts and transactions.

Benchmarks show that on identical hardware KeyDB can execute roughly twice as many queries per second as Redis with about 60% lower latency; its Active‑Replication feature simplifies hot‑standby failover, allowing write operations to be distributed across replicas and reducing operational costs.

Thread model: KeyDB splits Redis's original single main thread into a main thread and multiple worker I/O threads. Each worker thread handles listening, accepting connections, reading data, and protocol parsing. It uses SO_REUSEPORT so several threads can bind the same port and SO_INCOMING_CPU to bind incoming traffic to specific CPUs. A global lock protects shared in‑memory data, while the main thread (worker index 0) also runs serverCron tasks such as statistics, client connection management, DB resize/reshard, AOF handling, replication sync, and cluster duties.

Connection management: Every worker maintains its own client queues: clients_pending_write (synchronous writes) and clients_pending_asyncwrite (asynchronous writes). A global list clients_to_close tracks connections that must be closed asynchronously. Separate queues are needed because operations like Pub/Sub may require a thread different from the one that created the client to send data.

Example client structure snippet:

int iel; /* the event loop index we're registered with */

Fastlock mechanism: KeyDB implements a spin‑lock‑like fastlock based on a ticket structure:

struct ticket {
    uint16_t m_active;  // unlock +1
    uint16_t m_avail;   // lock +1
};
struct fastlock {
    volatile struct ticket m_ticket;
    volatile int m_pidOwner; // thread ID holding the lock
    volatile int m_depth;    // recursion depth
};

The lock uses GCC atomic built‑ins ( __atomic_load_2 , __atomic_fetch_add , __atomic_compare_exchange ) to compare m_active and m_avail . It offers two acquisition methods: try_lock (fails immediately) and lock (busy‑wait up to 1 048 576 iterations before calling sched_yield ). In KeyDB, try_lock is combined with the event loop so that a failed lock simply defers processing to the next epoll_wait cycle.

Active‑Replica: KeyDB supports multi‑master replication where replicas can be writable. Each replica carries a UUID to avoid circular replication, uses an rreplay API to package incremental commands with the local UUID, and timestamps keys (timestamp << 20 | auto‑increment) to detect conflicts; writes with older timestamps are rejected.

For complete benchmark results, configuration details, and source code, see the official documentation at https://docs.keydb.dev/blog/2019/10/07/blog-post/ and the GitHub repository https://github.com/JohnSully/KeyDB .

The article concludes with a reminder that the content is part of a larger series aimed at architects and developers.