Edge-triggered epoll: drain nonblocking work before waiting for another edge

What it is

The Linux epoll manual recommends nonblocking descriptors with edge-triggered notification and waiting for another event only after read or write reaches EAGAIN. Its example shows how partially consuming available data and then waiting again can stall. A readiness edge is not a promise that one operation corresponds to one complete application message. Linux epoll manual

Why it matters

An agent can make a server appear responsive by increasing a read buffer while leaving the event-loop state machine wrong. First identify the condition under which the descriptor is considered drained. Keep parser completeness, socket readiness and fairness between connections as separate concerns.

How to apply

• Confirm that descriptors used with EPOLLET are nonblocking. Trace the handler's loop and every path that returns to epoll_wait.
• Continue eligible I/O until the documented would-block condition or another terminal condition. Preserve partial application messages in a bounded parser buffer rather than waiting for one read to supply the whole message.
• If fairness requires stopping before the descriptor is drained, retain explicit runnable state so work resumes without requiring a new readiness edge.
• For EPOLLONESHOT, document which component rearms the descriptor and after which state transition. Include error and connection-close paths in that ownership rule.
• Propose a fixture that sends more data than one handler operation consumes, then stops sending. Verify that the receiver still processes the remaining available data.

Pitfalls

A larger buffer may mask the bug without fixing it. Unlimited draining can also starve other connections, so combine readiness correctness with a deliberate scheduling policy and resource limits. Level-triggered behavior differs and should not be assumed interchangeable during a refactor. This is a proposed event-loop review; no live traffic, throughput measurement or production load test is claimed.