DEV Community: Phạm Hồng Phúc

Redis's Event-Driven Architecture and the ae Event Loop

Phạm Hồng Phúc — Fri, 12 Jun 2026 08:38:01 +0000

One of the most common questions about Redis is: "Redis is single-threaded, so how can it handle thousands of concurrent connections?". But the more interesting question is: “Why would we need thousands of threads to handle thousands of connections in the first place?”
The answer lies in understanding the difference between doing work and waiting for work. A connection spends most of its lifetime waiting for data to arrive from the network. Waiting is not computation. If a server creates one thread for every connection, many of those threads spend most of their time blocked on I/O operations. Although blocked threads consume little CPU time, they still require memory for their stacks and introduce scheduling overhead.
Redis avoids this problem by using an event-driven architecture built on I/O multiplexing. Instead of dedicating one thread to each connection, a single thread asks the operating system: “Which connections are actually ready for work right now?”. The thread then processes only those connections.

Blocking I/O - The traditional model

The simplest server implementation uses blocking I/O:

while (1) {
    int fd = accept(server_fd, ...);   // wait for new connection
    handle_client(fd);                  // read, process, reply
    close(fd);                          // only then accept the next client
}

This design has an obvious limitation. While handle_client() is waiting for a client to send data, the entire server is blocked. No other connections can be accepted or processed. A traditional solution is to create one thread per connection:

while (1) {
    int fd = accept(server_fd, ...);
    pthread_create(&tid, NULL, handle_client, (void*)fd);
}

This model can work well at small scales. However, with thousands of concurrent connections, the overhead becomes significant. On many Linux systems, each thread reserves several megabytes of stack space by default. In addition, the OS must continually schedule and switch between threads, causing context-switch overhead.

Non-blocking I/O

Instead of allowing read() to block until data becomes available, a file descriptor can be configured non-blocking mode:

fcntl(fd, F_SETFL, O_NONBLOCK); 
ssize_t n = read(fd, buf, sizeof(buf)); 
if (n == -1 && errno == EAGAIN) { 
    // No data available yet 
}

The problem now becomes determining when to try again. Continuously checking every connection would waste CPU resources. This approach, known as busy waiting, keeps the CPU fully occupied even when no useful work is being performed. What is needed is a mechanism that allows the operating system to notify the application only when a file descriptor becomes ready.

I/O multiplexing

I/O multiplexing enables a single thread to monitor many file descriptors simultaneously.

select(): The first generation

fd_set read_fds;
FD_ZERO(&read_fds);
FD_SET(fd1, &read_fds);
FD_SET(fd2, &read_fds);
FD_SET(fd3, &read_fds);

// Block until at least one fd is ready
select(max_fd + 1, &read_fds, NULL, NULL, NULL);

// Then scan everything to find which ones are ready
for (int i = 0; i <= max_fd; i++) {
    if (FD_ISSET(i, &read_fds)) {
        read(i, buf, ...);
    }
}

select() has two major limitations

It is typically limited to FD_SETSIZE file descriptors (often 1024).
Each invocation requires scanning the entire set of descriptors, resulting in O(n) complexity.

pool() removes the fixed descriptor limit, but it still requires scanning all registered descriptors after each call.
epoll (in Linux) or kqueue (on maxos/bsd with an equivalent design) solves both problems by inverting the design: instead of handing the kernel a list to check on every call, you register once, and the kernel only notifies you about fds that actually have events.

int epfd = epoll_create1(0); 
struct epoll_event ev; 
ev.events = EPOLLIN; 
ev.data.fd = client_fd; 
epoll_ctl(epfd, EPOLL_CTL_ADD, client_fd, &ev); 
struct epoll_event events[MAX_EVENTS]; 
while (1) { 
    int n = epoll_wait(epfd, events, MAX_EVENTS, -1); 
    for (int i = 0; i < n; i++) { 
        handle(events[i].data.fd); 
    } 
}

The key advantage is that epoll_wait() returns only the file descriptors that are ready. If 10,000 connections are registered but only three receive data, Redis processes only those three connections instead of scanning all 10,000.

The ae event library

Redis does not use libraries such as libevent or libuv. Instead, Redis implements its own lightweight event library called ae (A simple Event Library, https://github.com/redis/redis/blob/unstable/src/ae.c). The central data structure is aeEventLoop:

typedef struct aeEventLoop { 
    int maxfd; 
    int setsize; 
    aeFileEvent *events; 
    aeFiredEvent *fired; 
    aeTimeEvent *timeEventHead; 
    aeApiState *apidata; 
} aeEventLoop;

Conceptually, the event loop consists of three parts:

aeEventLoop
├── File events
│ ├── acceptTcpHandler
│ ├── readQueryFromClient
│ └── sendReplyToClient
│
├── Time events
│ └── serverCron
│
└── Backend API
└── epoll / kqueue / select

File events handle socket activity. Time events execute periodic tasks that Redis must perform regardless of network activity. The backend API abstracts platform-specific multiplexing mechanisms.

The main event loop

Redis spends most of its lifetime executing the following loop:

void aeMain(aeEventLoop *eventLoop) { 
    eventLoop->stop = 0; 
    while (!eventLoop->stop) { 
        aeProcessEvents(eventLoop, 
        AE_ALL_EVENTS | 
        AE_CALL_BEFORE_SLEEP | 
        AE_CALL_AFTER_SLEEP); 
    } 
}

Conceptually, each iteration follows this sequence:

aeMain()
↓
aeProcessEvents()
↓
epoll_wait() / kqueue()
↓
Process file events
↓
Process time events
↓
Repeat forever

This design allows Redis to react efficiently to both incoming network requests and scheduled maintenance tasks.

File events and time events

Redis supports two categories of events.

File events

File events are triggered by socket activity. Examples include: acceptTcpHandler, readQueryFromClient, sendReplyToClient. These handlers manage client connections and network communication.

Time events

Time events execute periodically. The most important example is serverCron(). By default, Redis executes serverCron() approximately every 100 milliseconds (determined by the hz configuration parameter). serverCron() performs tasks such as:

Running the active expiration cycle
Collecting statistics
Managing client timeouts
Maintaining replication state,
Performing persistence-related housekeeping,
Executing cluster maintenance tasks.

Without time events, Redis would respond only to network activity and could not perform background maintenance.

Full lifecycle of a request inside ae event loop

To make it concrete, trace a SET key value from start to finish:

Step 1 (server start): During initialization, Redis registers the listening socket: server socket → acceptTcpHandler. Whenever a new connection arrives, the event loop invokes acceptTcpHandler().
Step 2 (client connects): When epoll_wait() reports that the server socket is ready: accept() → new client fd → aeCreateFileEvent(..., readQueryFromClient). Redis registers a readable file event for the client socket.
Step 3 (receive the command): The client sends 3\r\n$3\r\nSET\r\n.... The event loop detects that the client socket is readable and invokes: readQueryFromClient(). The command is copied into: client→querybuf.
Step 4 (parse and execute): Redis parses the RESP protocol, identifies the SET command, locates the appropriate command implementation, and executes it. The reply is generated in memory and appended to the client's output buffer. No I/O happens at this step, it is purely a memory operation.
Step 5 (send the reply): In the same loop iteration (after processing all read events), Redis calls the write handler to write() the reply buffer to the socket. If the reply buffer is large and cannot be flushed in one call, Redis registers a write event handler to continue flushing on the next iteration.

Why Single-Threaded Execution Works Well

A common misconception is that more threads always improve performance. Additional threads are beneficial primarily when the workload is limited by available CPU resources. Many Redis operations, such as GET and SET, perform relatively little computation: lookup key → retrieve value from memory → generate response. For these workloads, using multiple execution threads can increase overhead due to:

synchronization mechanisms protecting shared data,
context switching performed by the operating system,
cache coherence traffic between CPU cores.

By executing commands in a single thread, Redis avoids these costs entirely. This design simplifies the implementation and enables very high throughput for typical in-memory workloads.

The limits of this model

Single-threading has one clear weakness: one blocking command blocks the entire server.

KEYS * on a database with 10 million keys → O(n) scan → every other client waits for the entire duration. This is why KEYS is banned in production and replaced by SCAN (cursor-based, scanning a small portion per call).

Similarly: LRANGE mylist 0 -1 on a list with a million elements, SORT without LIMIT, SMEMBERS on a huge set — all commands that can stall the event loop.

Redis 6.0 partially addressed this with threaded I/O: still single-threaded for command execution, but uses multiple threads for reading and writing sockets. The reason: at high connection rates, read() and write() syscalls start consuming a meaningful share of time relative to command execution. Threaded I/O lets Redis exploit multiple cores without breaking the data model.

Redis 7.0 goes further with Redis Cluster sharding, distributing both data and load across multiple processes — each process still single-threaded — scaling out rather than up.

What actually happens when a Redis client connects?

Phạm Hồng Phúc — Thu, 11 Jun 2026 13:53:24 +0000

Nowadays, almost all Redis deployments use TCP as the primary connection protocol. Redis also supports Unix Domain Socket (UDS) when the client and server run on the same machine. UDS bypasses the TCP/IP stack and network interface entirely, typically reducing latency by 30–40% compared to TCP localhost — though the exact gain depends on workload. Because UDS requires co-location, TCP remains the universal default.

Why Redis uses TCP?

TCP fits Redis for the following reasons

Persistent, stateful connections: Redis processes one command at a time per client, in strict order: the client sends a command, waits for the reply, then sends the next. This request-response model requires a persistent, stateful connection, which TCP provides. Each TCP connection is uniquely identified by a 4-tuple (src_ip, src_port, dst_ip, dst_port), letting Redis maintain per-client state: current database index, transaction state (MULTI/EXEC), subscription lists, and so on. UDP is connectionless and stateless; a server would have to re-identify the client on every single datagram, pushing all that state management into application code.
In-order delivery: Redis uses RESP (Redis Serialization Protocol), which is a stream-based protocol. Commands arrive as a continuous byte stream, and Redis parses them sequentially. If bytes arrived out of order, the parser would break. TCP guarantees the stream is always ordered and complete.
Reliability: TCP automatically retransmits lost packets. Redis does not need to write any retry logic itself; the OS handles it transparently.
Flow control: TCP's sliding window prevents a fast client from overwhelming Redis's read buffer. Every TCP packet Redis sends back to the client carries an rwnd (receive window) value, a number the OS stamps automatically, representing free space remaining in the buffer. The client treats this as a hard cap on how much data it can have in flight. As Redis reads and drains its buffer, rwnd grows, and the client can send more. If Redis falls behind, rwnd shrinks toward zero, and the client throttles itself automatically. Redis never writes a line of code for this — the kernel manages it entirely.
Pipelining: Because TCP preserves byte order across the entire stream, clients can send many commands in one batch without waiting for individual replies. The server reads commands back-to-back from the stream and sends replies in the same order. This is pipelining, and it would be impossible without a reliable, ordered byte stream.

The above diagram describes three phases in Redis server when a Redis client connects for the first time

Accept phase
- The OS and Redis work asynchronously. When a client calls connect(), the OS kernel handles the entire TCP handshake (SYN → SYN-ACK → ACK) on its own, Redis is not involved. Once the handshake completes, the connection is pushed into the accept queue, sitting there until Redis is ready to pick it up.
- Meanwhile, Redis may be busy executing a command for another client. When it finishes, the event loop calls epoll_wait(). If a connection is waiting in the queue, epoll reports it, and only then does Redis call accept(). If Redis is already idle, it calls accept() almost immediately.
Register phase: accept() returns a new file descriptor, an integer that uniquely identifies the connection (for example, fd = 7). Redis registers this fd with epoll (Linux) or kqueue (macOS/BSD). From this point, the OS automatically notifies Redis when data arrives on that fd, so Redis never has to poll in a loop. (To be more understandable, you should read about AE Event Loop).
Allocate phase: Redis allocates a client struct in memory for the connection. This includes a 16 KB read buffer to hold incoming command bytes streaming in over TCP, and a write buffer to hold responses waiting to be sent back. The buffer exists because TCP can split a single command like SET key value across multiple small segments — Redis collects the bytes until it has a complete command before parsing.

The cost of a connection

Opening a connection requires:

A file descriptor (an integer in the kernel)
A client struct in Redis memory, including the 16 KB read buffer and write buffer — roughly ~20 KB of RAM per connection in total
A slot in epoll's interest list
- epoll is a Linux kernel mechanism for monitoring multiple file descriptors simultaneously. Redis uses it to know when a client sends data — without constantly polling ("anything yet? anything yet?").
- epoll maintains an interest list inside the kernel — essentially a table of file descriptors that Redis has registered and wants to be notified about. Each entry in that table is a slot, containing: the file descriptor to watch (e.g. fd = 7), the event type to listen for (e.g. EPOLLIN — data is ready to read), and a pointer back to the corresponding client struct in Redis memory.
- When Redis calls epoll_ctl(ADD, fd) during the Register phase, it is essentially telling the kernel: "add this fd to the interest list, and notify me when it has data."
- Each slot occupies a small amount of kernel memory (a few dozen bytes). More importantly, epoll has a limit on how many fds it can watch simultaneously — a limit typically bounded by ulimit -n at the OS level. So every new connection doesn't just cost RAM on the Redis side; it also consumes a finite slot in the kernel's interest list. In systems with thousands of clients, microservices, workers, cron jobs, if every service opens its own dedicated connection, it is easy to hit Redis's maxclients limit (default: 10000) or the OS-level ulimit -n. The solution is connection pooling.

Connection Pooling

A connection pool is a group of TCP connections that are pre-created and reused. Instead of an application running connect() → use → close() on every request, the pool keeps connections alive and lends them out as needed. Two key configuration values to understand:

minIdle — the minimum number of connections kept ready at all times. This reduces latency spikes when traffic ramps up suddenly, since connections are already warm.
maxTotal — the upper limit on total connections in the pool. This prevents a single application from exhausting Redis's connection slots. Notice: connection pooling works best for long-running processes. In serverless or ephemeral environments where instances spin up and down frequently, persistent pooled connections can actually cause more churn, you may need a different strategy such as a sidecar proxy.

Pipelining

Normally, each command waits for the previous reply before the next command is sent. If the round-trip time (RTT) between client and server is 1 ms, 100 sequential commands take 100 ms of network wait time, even though each command executes in under 1 µs on the server.

Pipelining solves this by sending multiple commands in a single write, without waiting for each response. The client batches commands at the application layer; TCP delivers them in order; Redis reads and executes them sequentially and sends back all replies in one go. The result: 100 commands might complete in just over 1 ms instead of 100 ms.

One common misconception: pipelining is not a transaction. Commands are executed in order, but if command A fails, command B still executes. There is no atomicity. If you need all-or-nothing semantics, use MULTI/EXEC or a Lua script instead.

You can read the full details in the official Redis pipelining documentation.