KeyDB vs Redis: Multithreaded Architecture, Fastlock & Active‑Replica Explained

What is KeyDB?

KeyDB is a high‑performance branch of Redis that focuses on multithreading, memory efficiency, and high throughput. In addition to multithreading, KeyDB includes features available only in Redis Enterprise, such as Active Replication, FLASH storage support, and direct backup to AWS S3.

KeyDB maintains full compatibility with the Redis protocol, modules, and scripting, preserving atomicity guarantees for scripts and transactions. Because KeyDB development stays in sync with Redis, it is a superset of Redis functionality and can replace existing Redis deployments.

On identical hardware, KeyDB can execute roughly twice as many queries per second as Redis while reducing latency by about 60 %. Active‑Replication simplifies hot‑standby failover, allowing write operations to be distributed to replicas and enabling simple TCP‑based load balancing/failover. The high performance lets you do more with less hardware, lowering operational costs and complexity.

KeyDB Architecture Overview

Multithreaded Architecture

KeyDB splits Redis’s original single main thread into a main thread and multiple worker threads. Each worker thread is an I/O thread that listens on the port, accepts connections, reads data, and parses the protocol.

The implementation uses the SO_REUSEPORT socket option so that multiple threads can bind to the same port, and the SO_INCOMING_CPU option to bind each thread to a specific CPU for incoming data.

After parsing the protocol, each thread operates on in‑memory data protected by a global lock that coordinates multithreaded access.

The main thread is also a worker thread (index 0 in the worker array) and handles tasks that must run only in the main thread.

The main thread’s responsibilities are implemented in serverCron, which includes:

Statistics processing

Client connection management

Database resize and resharding

AOF handling

Replication master‑slave synchronization

Cluster‑mode tasks

Connection Management

In Redis, all connection management runs in a single thread. KeyDB assigns each worker thread a set of connections, maintaining a per‑thread connection list. A new field int iel records the event‑loop index (the thread that owns the connection).

KeyDB maintains three key data structures for connection handling: clients_pending_write: per‑thread list of pending synchronous writes clients_pending_asyncwrite: per‑thread list of pending asynchronous writes clients_to_close: global list of connections that need asynchronous closing

Separate synchronous and asynchronous queues are needed because some Redis APIs (e.g., pub/sub) publish from one thread while the subscriber may reside in another thread.

Synchronous sending is performed entirely within the same thread, as illustrated by the following diagram:

Asynchronous sending involves two threads communicating via a pipe:

int fdCmdWrite; // write pipe
int fdCmdRead;  // read pipe

When a thread needs to send data asynchronously, it checks whether the client belongs to the local thread; if not, it posts a write event to the owning thread’s pipe, which then adds the request to its event loop.

Redis sometimes closes client connections outside the owning thread, so KeyDB also maintains a global asynchronous close list.

Lock Mechanism

KeyDB implements a spin‑lock‑like mechanism called fastlock . The main data structures are:

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 for the owning thread
};

Atomic operations such as __atomic_load_2, __atomic_fetch_add, and __atomic_compare_exchange are used to compare m_active and m_avail to decide if the lock can be acquired.

Fastlock provides two acquisition methods:

try_lock : returns immediately on failure

lock : busy‑waits, then after 1 048 576 attempts yields the CPU with sched_yield KeyDB combines try_lock with the event loop to avoid busy‑waiting; a client’s dedicated lock is attempted before reading data, and if it fails, processing is deferred to the next epoll_wait cycle.

Active‑Replica

KeyDB supports a multi‑active replication mechanism where each replica can be writable. Key features include:

Each replica has a UUID to prevent circular replication.

A new rreplay API packages incremental commands with the local UUID.

Keys and values carry a timestamp‑based version number; conflicts are resolved by comparing timestamps, using a scheme that left‑shifts the current timestamp by 20 bits and appends a 44‑bit counter.

Documentation

For a complete list of commands and configuration details, see the official KeyDB documentation at https://docs.keydb.dev/docs/commands .