Mastering epoll: High-Performance I/O Multiplexing in Linux

What is epoll?

epoll is an extensible I/O event notification facility introduced in Linux kernel 2.5.44, designed to replace the POSIX select and poll system calls. Unlike select/poll, which scale O(n) with the number of monitored file descriptors, epoll can operate in O(1) time, offering high performance for large numbers of connections. It is similar to FreeBSD’s kqueue.

Creating an epoll instance

int epoll_create(int size);

The size argument hints at the maximum number of file descriptors to be monitored. The call returns a file descriptor that represents the epoll instance; it must be closed with close() when no longer needed to avoid descriptor leaks.

Registering events with epoll_ctl

int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

The op argument specifies the operation and can be one of the following macros: EPOLL_CTL_ADD – register a new file descriptor. EPOLL_CTL_MOD – modify the events associated with an existing descriptor. EPOLL_CTL_DEL – remove a descriptor from the epoll set.

epoll_event structure

typedef union epoll_data {
    void   *ptr;
    int     fd;
    __uint32_t u32;
    __uint64_t u64;
} epoll_data_t;

struct epoll_event {
    __uint32_t events;   /* Epoll events */
    epoll_data_t data;   /* User data */
};

Event flags

The events field can be a combination of the following macros: EPOLLIN – readable data or remote socket closed. EPOLLOUT – writable. EPOLLPRI – urgent data (out‑of‑band). EPOLLERR – error condition. EPOLLHUP – hang up. EPOLLET – enable edge‑triggered mode. EPOLLONESHOT – report the event only once.

Waiting for events with epoll_wait

int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);

The events buffer receives the triggered events. maxevents must not exceed the size passed to epoll_create. timeout is specified in milliseconds (0 returns immediately, -1 blocks indefinitely). The function returns the number of ready events, or 0 on timeout.

Why epoll outperforms select

Select iterates over all file descriptors to determine which are ready, leading to low efficiency when many descriptors are monitored, and it is limited to 1024 descriptors. epoll, by contrast, stores descriptors in a kernel‑managed red‑black tree and only returns those with active events, achieving O(1) performance. It also supports both level‑triggered (LT) and edge‑triggered (ET) modes, which have significant differences in performance and implementation complexity.