epoll¶

Purpose¶

epoll provides a scalable event notification mechanism for monitoring large numbers of file descriptors.

Unlike poll(), which scans every file descriptor on each call, epoll maintains an internal set of monitored file descriptors and only returns those that are ready.

Core Components¶

An epoll instance consists of two logical collections:

Component	Purpose
Interest List	Stores monitored file descriptors
Ready List	Stores file descriptors that are currently ready

Each monitored file descriptor is represented internally by an epitem.

Registration Flow¶

epoll_create()

        │

        ▼

epoll_ctl(ADD)

        │

        ▼

Interest List

        │

        ▼

epoll_wait()

Event Detection¶

epoll does not determine device readiness itself.

Instead, it calls the driver's standard .poll() callback.

epoll_wait()

        │

        ▼

driver .poll()

        │

        ▼

Ready event

        │

        ▼

Ready List

        │

        ▼

Userspace

The same driver callback is shared by:

poll()
select()
epoll()

Trigger Modes¶

Level Trigger (LT)¶

Level Trigger reports an event whenever the device remains ready.

Typical behavior:

Ready

↓

epoll_wait()

↓

Ready

↓

epoll_wait()

↓

Ready

Edge Trigger (ET)¶

Edge Trigger reports only readiness transitions.

Typical behavior:

Not Ready

↓

Ready

↓

Notify once

↓

Still Ready

↓

No notification

Applications normally continue reading until no more data is available.

Typical APIs¶

epoll_create1()

epoll_ctl()

epoll_wait()

Common Pitfalls¶

Warning

The Ready List is not the source of truth. Device readiness is always determined by the driver's current state.