Redis Event Loop

The ae Library

~500 lines of C that abstract over four kernel APIs.

src/ae.c defines a portable event-loop interface; src/ae_epoll.c, src/ae_kqueue.c, src/ae_evport.c, and src/ae_select.c are the four backend implementations selected at compile time. The interface offers four operations: register a file event (read or write callback on an fd), register a time event (one-shot or recurring callback at a deadline), run one iteration, and run forever.

aeEventLoop *aeCreateEventLoop(int setsize);
int aeCreateFileEvent(aeEventLoop *el, int fd, int mask,
                      aeFileProc *proc, void *clientData);
long long aeCreateTimeEvent(aeEventLoop *el, long long ms,
                            aeTimeProc *proc, void *clientData,
                            aeEventFinalizerProc *finalizerProc);
void aeMain(aeEventLoop *el);              ← spins forever

Inside aeMain, each iteration calls aeProcessEvents(), which computes the deadline of the soonest pending timer and uses that as the timeout for epoll_wait (or kqueue equivalent). The kernel sleeps the thread until either an fd becomes readable/writable or the timeout fires; on wake, the loop dispatches I/O callbacks first, then any expired timers, then loops back. There's no busy-wait, no explicit sleep — the kernel does the waiting.

Command Dispatch in processCommand

The hot path that every operation passes through.

When a client's read callback fires, Redis reads from the socket into the per-client query buffer and tries to parse a complete RESP request. RESP is line-based: a request like SET foo bar arrives as:

*3\r\n
$3\r\nSET\r\n
$3\r\nfoo\r\n
$3\r\nbar\r\n

The parser detects "I have 3 bulk strings, all complete" and hands the parsed argv to processCommand. That function:

1. lookup the command in commands.def (hash table by name)
2. validate arity, types, ACL permissions
3. if MULTI is in progress, queue the command on the MULTI list
4. if cluster: check slot ownership, possibly reply MOVED
5. if maxmemory exceeded: trigger eviction (synchronous!)
6. if AOF enabled: append command to AOF buffer
7. if writes need replication: append to replication backlog
8. cmd->proc(c)   ← actually run the command
9. enqueue reply bytes on the client's output buffer
10. register the client's fd for write-readiness if reply is queued

Step 8 is where the dataset actually changes. For most commands this is a single dictionary lookup and update. For complex commands (SORT, ZRANGEBYSCORE on a huge zset, SUNIONSTORE across large sets) it can be expensive — and because we're on the single thread, no other client gets served while it runs.

Pipelining: Many Commands per Round-Trip

The reason throughput exceeds (1/RTT) commands per second.

A naive Redis client sends one command, waits for the reply, then sends the next. With a 0.5 ms RTT, max throughput is 2000 ops/sec from a single client. Pipelining breaks this: the client sends N commands back-to-back without waiting, then reads N replies. The server receives all N in one or a few read calls, parses them, executes them sequentially, and the replies are batched on the wire.

// single command per round-trip: 2000 ops/s @ 0.5ms RTT
SET k1 v1   ← send, wait, recv
SET k2 v2   ← send, wait, recv
...

// pipeline: 100k+ ops/s
SET k1 v1\r\nSET k2 v2\r\nSET k3 v3\r\n... ← single send
+OK\r\n+OK\r\n+OK\r\n...                     ← single recv

From the server's perspective, pipelining is invisible: processCommand just runs sequentially through its queue. The win is the elimination of round-trip stalls and the amortization of syscall overhead — one read serving 100 commands instead of 100 separate read calls. Most production Redis clients (Lettuce, hiredis, redis-py's pipeline mode) buffer N commands client-side and flush together.

Blocking Commands (BLPOP, BRPOP, XREAD)

'Blocking' from the client's perspective; non-blocking from the server's.

BLPOP queue 5 waits up to 5 seconds for an item to appear in queue. The server doesn't actually block any thread — that would single-thread one waiting client for 5 seconds. Instead, the implementation:

1. check if queue is non-empty → if yes, pop and return immediately
2. otherwise, mark client.blocked = 1, attached to a "blocking_keys" map keyed on "queue"
3. set a timer for the timeout
4. return from processCommand without sending a reply
5. main loop continues serving other clients

When another client runs RPUSH queue x, that command's logic checks db->blocking_keys for "queue" and, if any clients are waiting, picks the longest-waiting one and serves the pop in the same RPUSH execution. The blocked client's reply gets enqueued on its output buffer; the next event loop iteration writes it.

If the timer fires first, the client gets (nil) and is unblocked. Either way, no thread was held — just a flag and a registration. The same pattern serves XREAD blocking reads, BLMPOP, BLMOVE, and pub/sub pattern subscriptions.

I/O Threading (Redis 6.0+)

Splitting wire I/O across multiple threads while keeping execution serial.

For workloads dominated by many small commands from many clients (typical of caching), the single thread can become the wire-I/O bottleneck rather than the execution bottleneck. Redis 6.0 added optional I/O threading. With io-threads 4 (and io-threads-do-reads yes), the loop becomes:

main thread:                       worker threads (3):
  epoll_wait                          ← waiting on barriers
  collect ready clients
  ↓
  distribute clients to N threads
  ↓ wait barrier --------------------- read socket, parse RESP
  ←-------------- collect parsed cmds
  ↓
  execute all cmds serially            ← idle
  ↓
  distribute replies to N threads
  ↓ wait barrier --------------------- write socket
  ←-------------- collect done

Crucially, command execution is still serial — only the read-from-socket and write-to-socket steps are parallelized. The data structures stay lock-free.

Tradeoffs: I/O threading adds barrier-synchronization overhead, so it's a loss on workloads with few clients or large pipelined batches (where wire I/O is already amortized). It helps most when CPU profile shows significant time in read(2), write(2), and RESP parsing — which usually means thousands of clients hitting many small operations. Common production setting: io-threads 4 for a 4-core box, 8 for an 8-core box.

Background I/O Threads (bio.c)

Three additional threads for fsync, fclose, and lazyfree.

Even without io-threads, Redis has had background helpers since 2.x via bio.c. Three named threads:

bio_close_file:    closes() AOF and replication files (close on big files
                   can stall on filesystem metadata)

bio_aof_fsync:     fsync()s the AOF file periodically under everysec mode,
                   keeping fsync latency off the main thread

bio_lazy_free:     frees large objects (DEL on 1M-entry hash) asynchronously
                   when UNLINK is used or lazyfree-* configs are enabled

Each is a producer/consumer queue: the main thread enqueues a job and continues; the bg thread pops and runs the syscall. UNLINK key instead of DEL key uses lazyfree, returning instantly while a worker frees the value's memory. For a hash with a million fields, this turns a 30 ms blocking DEL into a 1 µs UNLINK.

FAQ