EPOLLEXCLUSIVE Limits Wakeups Across epoll Instances

EPOLLEXCLUSIVE changes event distribution when several epoll instances register the same target file description. Without the flag, a readiness event can wake waiters associated with every interested epoll instance. With exclusive registrations, Linux can restrict that fan-out and reduce redundant wakeups.

The flag does not make delivery single-consumer, does not assign ownership of the target, and does not replace application-level coordination. Its contract is narrower: among epoll instances that registered a target with EPOLLEXCLUSIVE, one or more receive an event for a wakeup rather than requiring all of them to receive it.

Exclusivity applies between epoll instances

The flag is supplied when adding a target to an epoll interest list:

struct epoll_event ev = {
    .events = EPOLLIN | EPOLLEXCLUSIVE,
    .data.fd = listen_fd,
};

if (epoll_ctl(epfd, EPOLL_CTL_ADD, listen_fd, &ev) == -1) {
    perror("epoll_ctl");
}

This arrangement matters when separate epoll instances monitor the same target, such as workers that each own an event loop around a shared listening socket. The exclusive property belongs to the registration between an epoll instance and that target.

It is different from several threads blocking on one shared epoll file descriptor. EPOLLEXCLUSIVE addresses wakeup distribution across registrations in multiple epoll instances, not a generic mutex-like exclusion rule around epoll_wait().

One or more exclusive registrations may receive an event

The name can suggest a stronger guarantee than the interface provides. Linux documents that one or more exclusive epoll instances receive an event when a wakeup occurs.

Code therefore cannot treat the flag as a promise that exactly one worker runs for each readiness transition. Scheduling, readiness state, multiple events, and the target’s own I/O semantics remain relevant. The useful guarantee is reduced fan-out compared with the default case where all attached epoll instances can receive the event.

For a listening socket, a worker that wakes still has to perform accept() and handle normal races. Another worker may consume available work first, or more than one connection may already be queued. Exclusive wakeup selection does not reserve a connection for a particular waiter.

Nonexclusive registrations remain outside the restriction

A target can appear in several epoll instances with a mixture of exclusive and ordinary registrations. In that configuration, an event is delivered to all epoll instances that did not request EPOLLEXCLUSIVE, plus at least one of the exclusive instances.

That boundary is significant during partial migrations. Adding the flag only to some workers does not suppress wakeups for observers that retain ordinary registrations. Monitoring, diagnostics, or a legacy event loop can therefore keep the broader notification behavior even while another set of workers uses exclusive mode.

The result is not global exclusivity for the file description. It is a delivery rule applied to the subset of registrations that requested it.

The mode is fixed at EPOLL_CTL_ADD

EPOLLEXCLUSIVE may be specified only with EPOLL_CTL_ADD. Using it with EPOLL_CTL_MOD fails with EINVAL. Once an epoll-target pair was added with the flag, a later EPOLL_CTL_MOD for that pair also fails.

This makes exclusive mode a registration-time property rather than a mask that can be toggled in place. Changing the arrangement requires removing the registration and adding it again with the desired mode, with the usual coordination needed around any change to an active interest list.

The permitted companion event bits are also constrained. Linux allows EPOLLIN, EPOLLOUT, EPOLLWAKEUP, and EPOLLET with EPOLLEXCLUSIVE. EPOLLERR and EPOLLHUP are reported when applicable without needing to be requested. Unsupported combinations produce EINVAL.

An epoll file descriptor also cannot be used as the target of an exclusive registration. Specifying EPOLLEXCLUSIVE while the target itself refers to an epoll instance fails.

Reduced wakeups do not define work ownership

The thundering-herd cost appears when many waiters wake for work that only a smaller number can consume. EPOLLEXCLUSIVE moves part of that filtering into the kernel’s epoll wakeup path, which can reduce needless scheduling in affected designs.

That optimization stops at notification. It does not serialize reads, accepts, writes, or state transitions on the target. It also does not define fairness among exclusive epoll instances or turn readiness into a queue of worker assignments.

Applications still need I/O loops that tolerate readiness races and transient results. With edge-triggered operation, they also retain the normal obligation to drain work according to edge-triggered semantics. The exclusive flag changes which epoll instances are woken; it does not change the underlying target’s readiness model.

The practical boundary is precise: EPOLLEXCLUSIVE is a wakeup-distribution control for shared targets across epoll instances. It can reduce herd behavior without converting epoll into a work scheduler or a single-consumer dispatch primitive.