Netty 4.2.x 源码深度解析 (十三)：Epoll 传输 —— Linux 高性能 IO 的 Netty 实现

在 Linux 平台上，JDK 自带的 Selector 底层基于 epoll 系统调用，但受限于 JDK NIO 的抽象层设计------SelectionKey 遍历、interestOps 管理、Selector.select() 的唤醒机制------无法充分发挥 epoll 的全部性能潜力。Netty 早在 4.0 时代就引入了 Epoll 原生传输，绕过 JDK 的 Selector 抽象直接调用 epoll_create、epoll_ctl、epoll_wait 系统调用，配合 eventfd 唤醒、timerfd 定时、writev 批量写入等 Linux 特性，在事件获取、批量写入、内存拷贝三个维度上全面超越 JDK NIO 实现。到了 4.2 版本，Epoll 传输进一步适配 IoHandler/IoHandle/IoRegistration 三层抽象架构，EpollIoHandler 取代旧版 EpollEventLoop 成为事件循环的核心，EpollMode.EDGE_TRIGGERED 被废弃并统一使用水平触发模式。本文将沿着"内核机制 → JNI 桥接 → 事件循环 → 事件处理 → Channel 实现 → 批量写入 → 接收优化"的递进逻辑，从 epoll 系统调用的底层原理出发，逐一分析 EpollIoHandler 的事件循环、EpollEventArray 的直接内存设计、EpollSocketChannel 的读写实现、doWriteMultiple 的批量写入优化、EpollRecvByteAllocatorHandle 的接收缓冲区自适应，最后串联从 EpollIoHandler 到 AbstractEpollUnsafe 的完整 IO 处理链路。本文围绕 epoll 传输的核心实现，逐一解答以下问题：

• Netty Epoll 传输如何绕过 JDK Selector，通过 JNI 直接调用 epoll_create/epoll_ctl/epoll_wait 系统调用？EpollIoHandler 在事件获取、分发、唤醒、定时四个环节上相比 NioIoHandler 做了哪些结构性改进？
• EpollEventArray 如何通过直接内存（Buffer.allocateDirectBufferWithNativeOrder）和 Unsafe 访问，将 struct epoll_event 数组直接映射到 Java 堆外内存，实现零拷贝的事件读取？
• AbstractEpollStreamChannel.doWriteMultiple 如何利用 IovArray 和 writev 系统调用实现批量写入，相比逐 ByteBuf 写入减少多少系统调用次数？
• EpollRecvByteAllocatorHandle 如何利用 epoll 水平触发特性，在单次 epollInReady 中通过 maybeMoreDataToRead() 和 continueReading() 循环读尽数据？

一、Epoll 内核机制速览：epoll_create/epoll_ctl/epoll_wait 三件套

Linux IO 多路复用的演进经历了三个阶段。最早的 select 系统调用要求内核遍历所有注册的文件描述符（时间复杂度 O(n)），且 fd_set 位图默认仅支持 1024 个文件描述符。poll 通过 struct pollfd 数组解除了数量限制，但每次调用仍需拷贝整个数组到内核并遍历所有条目，依然是 O(n) 复杂度。epoll 的出现彻底改变了这一局面：它将"注册文件描述符"和"等待就绪事件"拆分为两个独立的系统调用------epoll_ctl 和 epoll_wait，内核内部维护一棵红黑树存储所有注册的 fd，就绪的 fd 被放入一个双向链表，epoll_wait 仅需从就绪链表中取出事件，时间复杂度 O(1)。

epoll 的核心 API 由三个系统调用组成：

epoll_create(int size) / epoll_create1(int flags) ：在内核创建一个 epoll 实例，返回一个 epoll 文件描述符（epollFd）。epoll_create1 支持 EPOLL_CLOEXEC 标志，确保在 exec 系统调用时自动关闭 epoll 实例，避免文件描述符泄漏。Netty 在 JNI 层使用的是 epoll_create1(EPOLL_CLOEXEC)。

epoll_ctl(int epfd, int op, int fd, struct epoll_event *event) ：向 epoll 实例注册（EPOLL_CTL_ADD）、修改（EPOLL_CTL_MOD）或删除（EPOLL_CTL_DEL）文件描述符。每次调用需要指定关注的事件类型（位掩码）和关联的用户数据。

epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout)：阻塞等待就绪事件，返回就绪事件的数量。仅返回活跃的 fd 而非遍历全部注册的 fd，这是 epoll 相比 select/poll 最大的性能优势。

struct epoll_event 是 epoll 的核心数据结构。Linux 内核 UAPI 头文件（include/uapi/linux/eventpoll.h）中的定义为：

struct epoll_event {
    __poll_t events;   // 事件标志（4 字节，等价于 unsigned int）
    __u64    data;     // 用户数据（8 字节）
} EPOLL_PACKED;

glibc 用户空间头文件（<sys/epoll.h>）将其中的 data 字段封装为联合体，提供更灵活的访问方式：

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 (4 bytes)
    epoll_data_t data;     // User data variable (8 bytes)
};

两者在内存布局上完全等价（都是 4 + 8 = 12 字节），glibc 的联合体只是访问同一个 8 字节区域的不同视图。

事件类型包括 EPOLLIN（可读）、EPOLLOUT（可写）、EPOLLERR（错误）、EPOLLRDHUP（对端关闭连接或半关闭写端）等。这些标志通过位掩码组合使用。

水平触发（Level Triggered, LT）与边缘触发（Edge Triggered, ET）是 epoll 的两种工作模式。LT 模式下，只要文件描述符上还有未处理的数据，epoll_wait 就会持续返回该事件；ET 模式下，事件仅在新数据到达或状态变化时触发一次，要求应用层必须使用非阻塞 IO 并循环读尽。Netty 4.2 中 EpollMode.EDGE_TRIGGERED 已被废弃，统一使用 LT 模式。原因在于：ET 模式下应用层处理复杂度高，必须在每次事件触发时循环读尽数据，否则可能永久丢失事件；而 LT 在 epoll 下性能已足够优秀，统一使用 LT 降低了维护成本并避免了边界场景下的 bug。

除了核心的 epoll 三件套，Linux 还提供了两个重要的辅助机制：

eventfd ：比 pipe 或 socketpair 更轻量的唤醒机制。创建一个 eventfd 文件描述符并注册到 epoll 实例，调用 write(eventfd, 1) 即可唤醒 epoll_wait，read(eventfd) 消费事件。eventfd 仅需一个文件描述符（pipe 需要两个），且内核开销更小。

timerfd ：将定时器转化为文件描述符的机制。timerfd_create(CLOCK_MONOTONIC, TFD_NONBLOCK) 创建一个定时器 fd，timerfd_settime() 设置超时时间，超时后该 fd 变为可读，epoll_wait 可以统一监听 IO 事件和定时器事件。这意味着 Netty 的定时任务调度不需要额外的 ScheduledExecutorService 线程，而是融入 epoll 的事件模型中。

以下是这三层架构的映射关系：

二、Epoll 与 Native：可用性检测与 JNI 桥接

Epoll 类是 epoll 可用性检测的门面类，不包含任何业务逻辑，主要提供五个静态方法：isAvailable()、ensureAvailability()、unavailabilityCause()、isTcpFastOpenClientSideAvailable()、isTcpFastOpenServerSideAvailable()。其核心职责是在 JVM 启动时通过 JNI 调用验证当前环境是否支持 epoll 原生传输。

Epoll.isAvailable() 的检测逻辑在类加载时的静态初始化块中完成。检测分为以下步骤：

1. 检查 noNative 标志 ：若 io.netty.transport.noNative 系统属性为 true，则直接标记不可用，跳过所有 JNI 检测。
2. 调用 Native.newEpollCreate() ：通过 JNI 调用 epoll_create1(EPOLL_CLOEXEC) 创建临时 epoll 实例，验证内核是否支持 epoll 系统调用。
3. 调用 Native.newEventFd() ：通过 JNI 调用 eventfd(0, EFD_NONBLOCK) 创建临时 eventfd，验证内核是否支持 eventfd。
4. 清理临时资源 ：无论成功与否，在 finally 块中关闭临时创建的 epollFd 和 eventFd。

此外，Native.offsetofEpollData() 在 JNI 库加载时就被调用，用于验证 epoll_event 结构体的内存布局偏移量，确保 Java 侧可以直接通过偏移量访问 native 内存中的事件数据。

时序图：Epoll 可用性检测的完整流程

以下是 Epoll 类的静态初始化块核心代码：

io.netty.channel.epoll.Epoll

// 静态初始化块：通过 JNI 调用检测 epoll 可用性
static {
    Throwable cause = null;

    if (SystemPropertyUtil.getBoolean("io.netty.transport.noNative", false)) {
        // 通过系统属性显式禁用原生传输
        cause = new UnsupportedOperationException(
                "Native transport was explicit disabled with -Dio.netty.transport.noNative=true");
    } else {
        FileDescriptor epollFd = null;
        FileDescriptor eventFd = null;
        try {
            // 创建临时 epoll 实例，验证内核支持
            epollFd = Native.newEpollCreate();
            // 创建临时 eventfd，验证内核支持
            eventFd = Native.newEventFd();
        } catch (Throwable t) {
            cause = t;
        } finally {
            // 无论成功与否，释放临时资源
            if (epollFd != null) {
                try {
                    epollFd.close();
                } catch (Exception ignore) {
                    // ignore
                }
            }
            if (eventFd != null) {
                try {
                    eventFd.close();
                } catch (Exception ignore) {
                    // ignore
                }
            }
        }
    }
    UNAVAILABILITY_CAUSE = cause;
}

ensureAvailability() 在 EpollIoHandler 的实例初始化块中被调用，形成双重保障：

io.netty.channel.epoll.Epoll

// 不可用时抛出 UnsatisfiedLinkError，确保在使用 Epoll 前 JNI 已正确加载
public static void ensureAvailability() {
    if (UNAVAILABILITY_CAUSE != null) {
        throw (Error) new UnsatisfiedLinkError(
                "failed to load the required native library").initCause(UNAVAILABILITY_CAUSE);
    }
}

Native 类是 JNI 桥接层的核心，所有 native 方法声明集中在此。关键的 epoll 事件常量通过 NativeStaticallyReferencedJniMethods 静态绑定，避免每次 JNI 调用的开销：

io.netty.channel.epoll.Native

// epoll 事件标志：通过静态 JNI 方法绑定，避免每次调用 JNI
public static final int EPOLLIN = epollin();        // 可读
public static final int EPOLLOUT = epollout();       // 可写
public static final int EPOLLRDHUP = epollrdhup();    // 对端关闭
public static final int EPOLLET = epollet();         // 边缘触发标志，用于 eventFd/timerFd 内部注册
public static final int EPOLLERR = epollerr();       // 错误

Native.epollWait() 的返回值设计是一个精巧的 packed long 编码。其核心版本 epollWait(epollFd, events, timerFd, timeoutSec, timeoutNs, millisThreshold) 返回一个 long 值，高 32 位是就绪事件数量，低 8 位是 timer 标志，一次 JNI 调用同时返回事件数和定时器状态，减少 JNI 调用次数：

io.netty.channel.epoll.Native

// 从 packed long 中提取就绪事件数量（高 32 位）
static int epollReady(long result) {
    return (int) (result >> 32);
}

// 从 packed long 中提取 timer 标志（低 8 位）
static boolean epollTimerWasUsed(long result) {
    return (result & 0xff) != 0;
}

三、EpollIoHandler：epoll 事件循环的核心实现

EpollIoHandler 是 epoll 传输的事件循环核心，其类声明为 public class EpollIoHandler implements IoHandler。它持有 epoll 实例（epollFd）、唤醒 fd（eventFd）、定时器 fd（timerFd）、注册信息映射（IntObjectMap<DefaultEpollIoRegistration>）、就绪事件数组（EpollEventArray）以及 NativeArrays 聚合对象。

EpollIoHandler 的实例初始化块中调用了 Epoll.ensureAvailability()，确保该类只能在 Linux 平台（且 epoll 可用时）被实例化：

io.netty.channel.epoll.EpollIoHandler

// 实例初始化块：确保 epoll 可用，实现双重保障
{
    Epoll.ensureAvailability();
}

3.1 openFileDescriptors()：创建 epoll 实例

openFileDescriptors() 方法负责创建 epoll 实例、eventfd 和 timerfd，并将 eventFd 和 timerFd 注册到 epoll 实例中。注意 eventFd 和 timerFd 都使用了 EPOLLET（边缘触发）模式，因为只需要获取一次通知，不需要循环读取：

io.netty.channel.epoll.EpollIoHandler#openFileDescriptors

// 创建 epoll 实例、eventfd 和 timerfd，支持 CRaC 检查点恢复
public void openFileDescriptors() {
    boolean success = false;
    FileDescriptor epollFd = null;
    FileDescriptor eventFd = null;
    FileDescriptor timerFd = null;
    try {
        this.epollFd = epollFd = Native.newEpollCreate();
        this.eventFd = eventFd = Native.newEventFd();
        try {
            // eventFd 使用 EPOLLET 边缘触发，只需一次通知
            Native.epollCtlAdd(epollFd.intValue(), eventFd.intValue(),
                    Native.EPOLLIN | Native.EPOLLET);
        } catch (IOException e) {
            throw new IllegalStateException("Unable to add eventFd filedescriptor to epoll", e);
        }
        this.timerFd = timerFd = Native.newTimerFd();
        try {
            // timerFd 同样使用 EPOLLET 边缘触发
            Native.epollCtlAdd(epollFd.intValue(), timerFd.intValue(),
                    Native.EPOLLIN | Native.EPOLLET);
        } catch (IOException e) {
            throw new IllegalStateException("Unable to add timerFd filedescriptor to epoll", e);
        }
        success = true;
    } finally {
        if (!success) {
            // 任何一步失败，关闭已创建的文件描述符
            closeFileDescriptor(epollFd);
            closeFileDescriptor(eventFd);
            closeFileDescriptor(timerFd);
        }
    }
}

3.2 nextWakeupNanos 三段式唤醒状态机

nextWakeupNanos 是 EpollIoHandler 的核心并发控制机制，通过 AtomicLong 的 CAS 操作实现无锁状态转换。三种状态：

• AWAKE (-1L)：表示 EventLoop 已唤醒，正在处理任务或 IO 事件。
• NONE (Long.MAX_VALUE) ：表示无定时任务，epoll_wait 可以无限期阻塞。
• 其他值 T ：表示有定时任务，epoll_wait 应该在 T 时刻唤醒。

wakeup() 方法利用这个状态机避免重复写入 eventfd：

io.netty.channel.epoll.EpollIoHandler#wakeup

// 三段式唤醒状态机：仅在非 AWAKE 状态时才写入 eventfd
public void wakeup() {
    // 同线程无需唤醒；跨线程则通过 CAS 检测状态
    if (!executor.isExecutorThread(Thread.currentThread())
            && nextWakeupNanos.getAndSet(AWAKE) != AWAKE) {
        // 只有旧值非 AWAKE 时才写入 eventfd，避免重复写入
        Native.eventFdWrite(eventFd.intValue(), 1L);
    }
}

3.3 run() 核心事件循环

run(IoHandlerContext) 是事件循环的入口方法，其核心流程如下：

io.netty.channel.epoll.EpollIoHandler#run

public int run(IoHandlerContext context) {
    int handled = 0;
    try {
        // 1. 策略判定：CONTINUE / BUSY_WAIT / SELECT
        int strategy = selectStrategy.calculateStrategy(selectNowSupplier, !context.canBlock());
        switch (strategy) {
            case SelectStrategy.CONTINUE:
                // 无需阻塞等待，直接返回
                return 0;

            case SelectStrategy.BUSY_WAIT:
                // 非阻塞轮询，立即返回就绪事件
                strategy = epollBusyWait();
                break;

            case SelectStrategy.SELECT:
                // 2. pendingWakeup 兜底机制
                if (pendingWakeup) {
                    // eventfd 已被写入但 epoll_wait 尚未消费，使用固定 1 秒超时兜底
                    strategy = epollWaitTimeboxed();
                    if (strategy != 0) {
                        break;
                    }
                    // 超时未收到事件，说明 eventfd 写入可能丢失
                    logger.warn("Missed eventfd write (not seen after > 1 second)");
                    pendingWakeup = false;
                    if (!context.canBlock()) {
                        break;
                    }
                    // fall-through to normal epoll wait
                }

                // 3. 获取当前截止时间，决定是否需要修改 timerfd
                long curDeadlineNanos = context.deadlineNanos();
                if (curDeadlineNanos == -1L) {
                    curDeadlineNanos = NONE; // 无定时任务
                }
                nextWakeupNanos.set(curDeadlineNanos);
                try {
                    if (context.canBlock()) {
                        if (curDeadlineNanos == prevDeadlineNanos) {
                            // timerfd 无需修改，直接调用 epoll_wait
                            strategy = epollWaitNoTimerChange();
                        } else {
                            // timerfd 需要重新设置
                            long result = epollWait(context, curDeadlineNanos);
                            // 从 packed long 中拆包
                            strategy = Native.epollReady(result);
                            prevDeadlineNanos = Native.epollTimerWasUsed(result)
                                    ? curDeadlineNanos : NONE;
                        }
                    }
                } finally {
                    // 4. 检测是否在 epoll_wait 期间被外部唤醒
                    if (nextWakeupNanos.get() == AWAKE
                            || nextWakeupNanos.getAndSet(AWAKE) == AWAKE) {
                        pendingWakeup = true;
                    }
                }
                // fallthrough
            default:
        }
        // 5. 处理就绪事件
        if (strategy > 0) {
            int packed = processReady(events, strategy);
            // 从 packed int 中拆包：真实 IO 事件数 和 timer 标志
            handled = packed >>> 1;
            if ((packed & 1) != 0) {
                prevDeadlineNanos = NONE; // timer 触发，重置截止时间
            }
        }

        // 6. 动态扩容 EpollEventArray
        if (allowGrowing && strategy == events.length()) {
            events.increase();
        }
    } catch (Error e) {
        throw e;
    } catch (Throwable t) {
        handleLoopException(t);
    }
    return handled;
}

注：为聚焦核心逻辑，上述代码省略了 shouldReportActiveIoTime() 性能指标上报。实际源码中 CONTINUE 分支、strategy > 0 分支、else 分支均包含 shouldReportActiveIoTime() 判断以记录活跃 IO 时间。

这个 run() 方法体现了 EpollIoHandler 的四大设计精髓：

1. 策略驱动 ：SelectStrategy 将 CONTINUE（不阻塞）、BUSY_WAIT（非阻塞轮询）、SELECT（阻塞等待）三种策略分离，EpollIoHandler 根据策略选择不同的 epollWait 变体。
2. pendingWakeup 兜底 ：当 eventfd 被写入但 epoll_wait 尚未消费时，pendingWakeup 为 true。此时使用 epollWaitTimeboxed()（固定 1 秒超时）作为兜底，防止因异常的 syscall 失败导致事件丢失。
3. timerfd 增量更新 ：只有当 curDeadlineNanos != prevDeadlineNanos 时才修改 timerfd，避免不必要的系统调用。
4. packed 返回值 ：processReady() 返回 packed int，高效编码 IO 事件数和 timer 状态。

3.4 processReady() 事件分发

processReady() 遍历 EpollEventArray 中的就绪事件，将事件分发给对应的 DefaultEpollIoRegistration。其 packed int 返回值设计：每个真实 IO 事件加 2（result += 2），timerfd 事件加 1（result |= 1），拆包时 handled = packed >>> 1 获取事件数，(packed & 1) != 0 判断 timer 是否触发：

io.netty.channel.epoll.EpollIoHandler#processReady

// packed int 返回值：每个 IO 事件加 2，timer 触发加 1
private int processReady(EpollEventArray events, int ready) {
    int result = 0;
    for (int i = 0; i < ready; i++) {
        final int fd = events.fd(i);
        if (fd == eventFd.intValue()) {
            // eventFd 被唤醒，消费 pendingWakeup 标志
            pendingWakeup = false;
        } else if (fd == timerFd.intValue()) {
            // timerFd 超时，标记 timer 触发
            result |= 1;
        } else {
            // 真实 IO 事件：从 registrations 中查找对应的注册信息
            result += 2;
            final long ev = events.events(i);
            DefaultEpollIoRegistration registration = registrations.get(fd);
            if (registration != null) {
                registration.handle(ev);
            } else {
                // fd 已不再使用，从 epoll 中移除
                try {
                    Native.epollCtlDel(epollFd.intValue(), fd);
                } catch (IOException ignore) {
                    // 忽略异常，确保清理
                }
            }
        }
    }
    return result;
}

3.5 DefaultEpollIoRegistration 的三态状态机

DefaultEpollIoRegistration 是 EpollIoHandler 的内部类，实现了 IoRegistration 接口。它通过 RegistrationState 枚举维护一个三态状态机：Pending（未通过 EPOLL_CTL_ADD 添加到 epoll）、Added（已添加）、Cancelled（已移除）。状态转换仅在 submit() 和 cancel() 中发生：

io.netty.channel.epoll.EpollIoHandler.DefaultEpollIoRegistration#submit

// 根据当前状态执行不同的 epoll_ctl 操作
public long submit(IoOps ops) {
    EpollIoOps epollIoOps = cast(ops);
    try {
        synchronized (this) {
            switch (state) {
                case Cancelled:
                    return -1;
                case Pending:
                    if (epollIoOps.value == EpollIoOps.NONE.value) {
                        // NONE 表示移除注册，但尚未添加，直接返回
                        return 0;
                    }
                    // 首次添加：EPOLL_CTL_ADD
                    Native.epollCtlAdd(epollFd.intValue(), handle.fd().intValue(), epollIoOps.value);
                    state = RegistrationState.Added;
                    return epollIoOps.value;
                case Added:
                    if (epollIoOps.value == EpollIoOps.NONE.value) {
                        // NONE 表示不再关注任何事件，移除 fd
                        Native.epollCtlDel(epollFd.intValue(), handle.fd().intValue());
                        return 0;
                    }
                    // 修改已注册的事件：EPOLL_CTL_MOD
                    Native.epollCtlMod(epollFd.intValue(), handle.fd().intValue(), epollIoOps.value);
                    return epollIoOps.value;
                default:
                    throw new IllegalStateException();
            }
        }
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
}

cancel() 方法通过 synchronized 保证幂等，区分同线程（直接执行 cancel0()）和跨线程（通过 executor.execute(this::cancel0) 提交到 EventLoop 线程）两种路径：

io.netty.channel.epoll.EpollIoHandler.DefaultEpollIoRegistration#cancel

// 取消注册：synchronized 保证幂等，区分同线程和跨线程
public boolean cancel() {
    synchronized (this) {
        if (state == RegistrationState.Cancelled) {
            return false; // 已取消，幂等返回
        }
        state = RegistrationState.Cancelled;
    }
    if (executor.isExecutorThread(Thread.currentThread())) {
        cancel0(); // 同线程直接执行
    } else {
        executor.execute(this::cancel0); // 跨线程提交到 EventLoop
    }
    return true;
}

3.6 run() 完整事件循环时序图

四、EpollIoHandle 与 EpollIoOps：IO 事件抽象

EpollIoHandle 接口扩展了 IoHandle，增加了 FileDescriptor fd() 方法，用于返回底层 socket 的文件描述符，EpollIoHandler 通过此方法获取 fd 进行 epoll_ctl 操作：

io.netty.channel.epoll.EpollIoHandle

// 扩展 IoHandle，增加 fd() 方法返回底层文件描述符
public interface EpollIoHandle extends IoHandle {
    /**
     * Returns the {@link FileDescriptor} that used by this {@link IoHandle}.
     */
    FileDescriptor fd();
}

EpollIoHandle 的实现者是 AbstractEpollChannel.AbstractEpollUnsafe，其 fd() 方法返回 FileDescriptor（即 socket 对象），调用方通过 fd().intValue() 获取 int 型文件描述符，handle() 方法负责事件分发。

EpollIoOps 实现了 IoOps 接口，将 epoll 的事件标志封装为位掩码常量，通过 contains()、with()、without() 方法进行位运算组合：

io.netty.channel.epoll.EpollIoOps

// 预定义的事件常量，通过静态 JNI 方法获取底层值
public static final EpollIoOps EPOLLOUT = new EpollIoOps(Native.EPOLLOUT);
public static final EpollIoOps EPOLLIN = new EpollIoOps(Native.EPOLLIN);
public static final EpollIoOps EPOLLERR = new EpollIoOps(Native.EPOLLERR);
public static final EpollIoOps EPOLLRDHUP = new EpollIoOps(Native.EPOLLRDHUP);
public static final EpollIoOps EPOLLET = new EpollIoOps(Native.EPOLLET);
// NONE 表示不关注任何事件，用于从 epoll 移除 fd
public static final EpollIoOps NONE = new EpollIoOps(0);

// 位运算组合：添加事件标志
public EpollIoOps with(EpollIoOps ops) {
    if (contains(ops)) {
        return this;
    }
    return valueOf(value | ops.value());
}

// 位运算组合：移除事件标志
public EpollIoOps without(EpollIoOps ops) {
    if (!contains(ops)) {
        return this;
    }
    return valueOf(value & ~ops.value());
}

EpollIoOps 的 eventOf(int) 方法通过 EVENTS[] 缓存数组实现 O(1) 查找，命中则复用，未命中则新建，减少对象创建开销：

io.netty.channel.epoll.EpollIoOps

// 事件缓存数组：O(1) 查找，命中复用，未命中新建
static EpollIoEvent eventOf(int value) {
    if (value > 0 && value < EVENTS.length) {
        EpollIoEvent event = EVENTS[value];
        if (event != null) {
            return event;
        }
    }
    return new DefaultEpollIoEvent(new EpollIoOps(value));
}

AbstractEpollUnsafe.handle() 是事件分发的核心，按严格的顺序处理：EPOLLOUT（连接完成或写就绪） → EPOLLIN（读就绪） → EPOLLRDHUP（对端关闭）。这个顺序是经过长期实践验证的，不能随意更改------EPOLLOUT 必须优先处理，因为连接完成后才能进行读写；EPOLLIN 必须在 EPOLLRDHUP 之前处理，确保在关闭输入之前读取完所有数据：

io.netty.channel.epoll.AbstractEpollChannel.AbstractEpollUnsafe#handle

// 事件分发：EPOLLOUT → EPOLLIN → EPOLLRDHUP，顺序不可更改
public void handle(IoRegistration registration, IoEvent event) {
    EpollIoEvent epollEvent = (EpollIoEvent) event;
    int ops = epollEvent.ops().value;

    // 1. 首先检查 EPOLLOUT：连接完成或写就绪
    if ((ops & EPOLL_ERR_OUT_MASK) != 0) {
        epollOutReady();
    }

    // 2. 检查 EPOLLIN：读就绪
    if ((ops & EPOLL_ERR_IN_MASK) != 0) {
        epollInReady();
    }

    // 3. 检查 EPOLLRDHUP：对端关闭
    if ((ops & EPOLL_RDHUP_MASK) != 0) {
        epollRdHupReady();
    }
}

epollOutReady() 处理连接完成和写就绪两种场景：

io.netty.channel.epoll.AbstractEpollChannel.AbstractEpollUnsafe#epollOutReady

// 处理 EPOLLOUT 就绪：连接完成或写就绪
final void epollOutReady() {
    if (connectPromise != null) {
        // 连接未完成，完成连接
        finishConnect();
    } else if (!socket.isOutputShutdown()) {
        // 连接已完成，执行写操作
        super.flush0();
    }
}

时序图 ：AbstractEpollUnsafe.handle() 事件分发

五、EpollEventArray：struct epoll_event 的直接内存映射

EpollEventArray 是 epoll 传输性能优势的关键设计之一。它封装了 struct epoll_event 的直接内存数组，作为 epoll_wait 的就绪事件缓冲区，避免了 Java 堆内存与 native 内存之间的数据拷贝。

struct epoll_event 在 x86-64 Linux 上的内存布局为 12 字节（4 字节 events + 8 字节 data，内核通过 EPOLL_PACKED 宏即 __attribute__((packed)) 声明，消除 padding 以保持 32 位和 64 位布局一致）。EpollEventArray 不硬编码大小，而是通过 Native.sizeofEpollEvent() 和 Native.offsetofEpollData() 在运行期从 C 侧动态获取结构体大小和数据偏移量，确保跨平台兼容性。在 Java 侧精确计算每个事件的访问地址：

io.netty.channel.epoll.EpollEventArray

// Size of the epoll_event struct
private static final int EPOLL_EVENT_SIZE = Native.sizeofEpollEvent();
// The offset of the data union in the epoll_event struct
private static final int EPOLL_DATA_OFFSET = Native.offsetofEpollData();

构造器分配固定大小的直接内存，memoryAddress() 返回内存首地址直接传给 JNI 的 epoll_wait：

io.netty.channel.epoll.EpollEventArray

// 构造器：分配 length * sizeofEpollEvent 字节的直接内存
EpollEventArray(int length) {
    if (length < 1) {
        throw new IllegalArgumentException("length must be >= 1 but was " + length);
    }
    this.length = length;
    cleanable = Buffer.allocateDirectBufferWithNativeOrder(calculateBufferCapacity(length));
    memory = cleanable.buffer();
    memoryAddress = Buffer.memoryAddress(memory);
}

fd(int index) 和 events(int index) 方法通过偏移量直接从 native 内存中提取数据。events 位于 epoll_event 结构体的起始位置（偏移 0），fd 则需要加上 EPOLL_DATA_OFFSET 偏移量（位于 data 联合体处）：

io.netty.channel.epoll.EpollEventArray

// 从直接内存中读取文件描述符（位于 epoll_event 结构体 data 联合体处，偏移 EPOLL_DATA_OFFSET）
int fd(int index) {
    return getInt(index, EPOLL_DATA_OFFSET);
}

// 从直接内存中读取事件标志（位于 epoll_event 结构体起始位置，偏移 0）
int events(int index) {
    return getInt(index, 0);
}

// 底层内存访问：优先使用 Unsafe 直接内存访问
private int getInt(int index, int offset) {
    if (PlatformDependent.hasUnsafe()) {
        long n = (long) index * EPOLL_EVENT_SIZE;
        return PlatformDependent.getInt(memoryAddress + n + offset);
    }
    return memory.getInt(index * EPOLL_EVENT_SIZE + offset);
}

increase() 方法在需要扩容时，将容量翻倍并释放旧数组的内存。EpollIoHandler 中的 allowGrowing 策略控制是否允许扩容：

io.netty.channel.epoll.EpollEventArray

// 动态扩容：容量翻倍，释放旧数组内存
void increase() {
    length <<= 1; // 容量翻倍
    // 旧数据无需保留，直接分配新数组
    CleanableDirectBuffer buffer = Buffer.allocateDirectBufferWithNativeOrder(
            calculateBufferCapacity(length));
    cleanable.clean(); // 释放旧内存
    cleanable = buffer;
    memory = buffer.buffer();
    memoryAddress = Buffer.memoryAddress(buffer.buffer());
}

allowGrowing 策略：EpollIoHandler 构造时根据 maxEvents 参数决定，maxEvents == 0 时允许动态扩容（初始容量 4096），maxEvents > 0 时固定容量。当 processReady() 返回的 strategy == events.length()（数组被填满）且 allowGrowing 为 true 时触发 increase()：

io.netty.channel.epoll.EpollIoHandler

// allowGrowing 策略：maxEvents == 0 时允许动态扩容
if (maxEvents == 0) {
    allowGrowing = true;
    events = new EpollEventArray(4096);
} else {
    allowGrowing = false;
    events = new EpollEventArray(maxEvents);
}

以下是 EpollEventArray 与 struct epoll_event 的内存布局示意图：

与 JDK Selector 的事件获取相比，EpollEventArray 有两个核心优势：一是通过直接内存避免了内核到 Java 堆的数据拷贝；二是支持按索引 O(1) 访问，无需 Iterator 遍历。

六、EpollSocketChannel 与 EpollServerSocketChannel：Channel 的 Epoll 实现

AbstractEpollChannel 是 Epoll Channel 的抽象基类，继承 AbstractChannel 并实现 UnixChannel。它持有核心字段：socket（LinuxSocket）、ops（EpollIoOps）、registration（IoRegistration）、active、connectPromise 等。

doRegister() 是 Channel 注册到 EventLoop 的入口方法，通过 IoEventLoop.register() 获取 IoRegistration，成功后将初始 ops 提交到 epoll：

io.netty.channel.epoll.AbstractEpollChannel#doRegister

// 注册 Channel 到 EpollIoHandler
protected void doRegister(ChannelPromise promise) {
    ((IoEventLoop) eventLoop()).register((AbstractEpollUnsafe) unsafe()).addListener(f -> {
        if (f.isSuccess()) {
            registration = (IoRegistration) f.getNow();
            if (isActive()) {
                // Channel 已激活，立即提交 ops 注册到 epoll
                submitCurrentOps();
            }
            promise.setSuccess();
        } else {
            promise.setFailure(f.cause());
        }
    });
}

setFlag(int) 和 clearFlag(int) 通过位运算修改 ops，再调用 registration.submit(ops) 同步到 epoll。setFlag 中有优化：如果标志已经设置，则跳过系统调用：

io.netty.channel.epoll.AbstractEpollChannel#setFlag

// 设置事件标志，已设置则跳过系统调用
protected void setFlag(int flag) throws IOException {
    if (ops.contains(flag)) {
        return; // 标志已设置，节省系统调用
    }
    ops = ops.with(EpollIoOps.valueOf(flag));
    if (isRegistered()) {
        IoRegistration registration = registration();
        registration.submit(ops);
    }
}

doReadBytes(ByteBuf) 将数据从 socket 直接读取到 ByteBuf 的直接内存中，避免 JDK NIO 的 ByteBuffer 中间层：

io.netty.channel.epoll.AbstractEpollChannel#doReadBytes

// 从 socket 直接读取数据到 ByteBuf 的直接内存
protected final int doReadBytes(ByteBuf byteBuf) throws Exception {
    int writerIndex = byteBuf.writerIndex();
    int localReadAmount;
    if (byteBuf.hasMemoryAddress()) {
        // 直接内存路径：使用 recvAddress 直接从 socket 读取
        localReadAmount = socket.recvAddress(byteBuf.memoryAddress(), writerIndex, byteBuf.capacity());
    } else {
        // 堆内存路径：使用 internalNioBuffer 转换
        ByteBuffer buf = byteBuf.internalNioBuffer(writerIndex, byteBuf.writableBytes());
        localReadAmount = socket.recv(buf, buf.position(), buf.limit());
    }
    if (localReadAmount > 0) {
        byteBuf.writerIndex(writerIndex + localReadAmount);
    }
    return localReadAmount;
}

6.1 EpollServerSocketChannel

EpollServerSocketChannel 的 doBind() 方法依次执行绑定、TFO 设置、监听、标记 active 和提交 ops：

io.netty.channel.epoll.EpollServerSocketChannel#doBind

// 绑定端口并开始监听
protected void doBind(SocketAddress localAddress) throws Exception {
    super.doBind(localAddress);
    final int tcpFastopen;
    // 如果支持 TFO 服务端，设置 TCP Fast Open
    if (IS_SUPPORTING_TCP_FASTOPEN_SERVER && (tcpFastopen = config.getTcpFastopen()) > 0) {
        socket.setTcpFastOpen(tcpFastopen);
    }
    socket.listen(config.getBacklog());
    active = true;
    // 开始监听，提交 ops 注册到 epoll 以接收 EPOLLIN 事件
    submitCurrentOps();
}

newChildChannel() 创建子 Channel，将 accept() 返回的文件描述符包装为 EpollSocketChannel：

io.netty.channel.epoll.EpollServerSocketChannel#newChildChannel

// 接受新连接，创建 EpollSocketChannel 子 Channel
protected Channel newChildChannel(int fd, byte[] address, int offset, int len) throws Exception {
    return new EpollSocketChannel(this, new LinuxSocket(fd), address(address, offset, len));
}

6.2 EpollSocketChannel

EpollSocketChannel 的 doConnect0() 支持 TCP Fast Open（TFO），在连接建立时可以直接发送数据，减少一次 RTT：

io.netty.channel.epoll.EpollSocketChannel#doConnect0

// 支持 TCP Fast Open 的连接：连接时直接发送数据
boolean doConnect0(SocketAddress remote) throws Exception {
    if (IS_SUPPORTING_TCP_FASTOPEN_CLIENT && config.isTcpFastOpenConnect()) {
        ChannelOutboundBuffer outbound = unsafe().outboundBuffer();
        outbound.addFlush();
        Object curr;
        if ((curr = outbound.current()) instanceof ByteBuf) {
            ByteBuf initialData = (ByteBuf) curr;
            // TFO: 在 connect 时同时发送数据，减少一次 RTT
            long localFlushedAmount = doWriteOrSendBytes(
                    initialData, (InetSocketAddress) remote, true);
            if (localFlushedAmount > 0) {
                // Cookie 存在，TFO 成功，移除已写入的数据
                outbound.removeBytes(localFlushedAmount);
                return true;
            }
        }
    }
    return super.doConnect0(remote);
}

EpollSocketChannelUnsafe.prepareToClose() 处理 SO_LINGER 场景，使用 GlobalEventExecutor 延迟关闭以避免阻塞 EventLoop 线程：

io.netty.channel.epoll.EpollSocketChannel.EpollSocketChannelUnsafe#prepareToClose

// SO_LINGER 场景：使用 GlobalEventExecutor 延迟关闭，避免阻塞 EventLoop
protected Executor prepareToClose() {
    try {
        if (isOpen() && config().getSoLinger() > 0) {
            // 取消 epoll 注册，避免在关闭期间持续收到 IO 事件
            registration().cancel();
            return GlobalEventExecutor.INSTANCE;
        }
    } catch (Throwable ignore) {
        // 忽略异常，返回 null
    }
    return null;
}

时序图 ：EpollServerSocketChannel 从绑定到接受新连接的完整链路

七、doWriteMultiple：writev 批量写入的核心优化

doWriteMultiple 是 Epoll 传输在写密集型场景下的核心性能优化。它利用 Linux 的 writev 系统调用，将多个 ByteBuf 聚合为 iovec 数组，通过一次系统调用完成批量写入，大幅减少上下文切换和 JNI 调用次数。

AbstractEpollStreamChannel.doWrite() 是写操作的入口，通过 writeSpinCount 控制写操作次数，msgCount > 1 且当前消息是 ByteBuf 时走 doWriteMultiple() 批量写入，否则走 doWriteSingle() 单次写入，msgCount == 0 时清除 EPOLLOUT 标志退出循环：

io.netty.channel.epoll.AbstractEpollStreamChannel#doWrite

// 写操作入口：根据消息数量选择批量写入或单次写入
protected void doWrite(ChannelOutboundBuffer in) throws Exception {
    int writeSpinCount = config().getWriteSpinCount();
    do {
        final int msgCount = in.size();
        if (msgCount > 1 && in.current() instanceof ByteBuf) {
            // 多个 ByteBuf：走批量写入路径
            writeSpinCount -= doWriteMultiple(in);
        } else if (msgCount == 0) {
            // 所有消息已写入，清除 EPOLLOUT 标志
            clearFlag(Native.EPOLLOUT);
            return;
        } else { // msgCount == 1
            // 单个消息：走单次写入路径
            writeSpinCount -= doWriteSingle(in);
        }
    } while (writeSpinCount > 0);

    if (writeSpinCount == 0) {
        // writeSpinCount 耗尽，重新提交写任务
        clearFlag(Native.EPOLLOUT);
        eventLoop().execute(flushTask);
    } else {
        // 写缓冲区未清空，注册 EPOLLOUT 等待可写
        setFlag(Native.EPOLLOUT);
    }
}

doWriteMultiple(ChannelOutboundBuffer in) 的完整流程：获取 maxBytesPerGatheringWrite 限制 → 从 registration.attachment() 获取 NativeArrays → 取出 IovArray 并设置 maxBytes → in.forEachFlushedMessage(array) 将 ByteBuf 填充到 IovArray → array.count() >= 1 时调用 writeBytesMultiple(in, array) → in.removeBytes(0) 清理空缓冲区：

io.netty.channel.epoll.AbstractEpollStreamChannel#doWriteMultiple

// 批量写入：将多个 ByteBuf 聚合为 iovec 数组，通过 writev 一次写入
private int doWriteMultiple(ChannelOutboundBuffer in) throws Exception {
    final long maxBytesPerGatheringWrite = config().getMaxBytesPerGatheringWrite();
    IovArray array = ((NativeArrays) registration().attachment()).cleanIovArray();
    array.maxBytes(maxBytesPerGatheringWrite);
    // 将 flushed 消息填充到 IovArray 中
    in.forEachFlushedMessage(array);

    if (array.count() >= 1) {
        return writeBytesMultiple(in, array);
    }
    // 所有消息都是空缓冲区
    in.removeBytes(0);
    return 0;
}

writeBytesMultiple(in, array) 调用 socket.writevAddresses(array.memoryAddress(0), array.count())，一次 JNI 调用将多个 iovec 通过 writev 系统调用批量写入：

io.netty.channel.epoll.AbstractEpollStreamChannel#writeBytesMultiple

// 通过 writev 系统调用批量写入 iovec 数组
private int writeBytesMultiple(ChannelOutboundBuffer in, IovArray array) throws IOException {
    final long expectedWrittenBytes = array.size();
    assert expectedWrittenBytes != 0;
    final int cnt = array.count();
    assert cnt != 0;

    final long localWrittenBytes = socket.writevAddresses(array.memoryAddress(0), cnt);
    if (localWrittenBytes > 0) {
        adjustMaxBytesPerGatheringWrite(expectedWrittenBytes, localWrittenBytes, array.maxBytes());
        in.removeBytes(localWrittenBytes);
        return 1;
    }
    return WRITE_STATUS_SNDBUF_FULL;
}

当 ByteBuf 数量多但 IovArray 容量不足时，降级为使用 ByteBuffer 数组的 writev 路径：

io.netty.channel.epoll.AbstractEpollStreamChannel#writeBytesMultiple

// 降级路径：使用 ByteBuffer 数组而非直接内存 iovec
private int writeBytesMultiple(
        ChannelOutboundBuffer in, ByteBuffer[] nioBuffers, int nioBufferCnt,
        long expectedWrittenBytes, long maxBytesPerGatheringWrite) throws IOException {
    if (expectedWrittenBytes > maxBytesPerGatheringWrite) {
        expectedWrittenBytes = maxBytesPerGatheringWrite;
    }
    final long localWrittenBytes = socket.writev(nioBuffers, 0, nioBufferCnt, expectedWrittenBytes);
    if (localWrittenBytes > 0) {
        adjustMaxBytesPerGatheringWrite(expectedWrittenBytes, localWrittenBytes, maxBytesPerGatheringWrite);
        in.removeBytes(localWrittenBytes);
        return 1;
    }
    return WRITE_STATUS_SNDBUF_FULL;
}

批量写入与单次写入的性能对比：writev 一次系统调用写入多个 ByteBuf，减少上下文切换和 JNI 调用次数，在写密集型场景下性能提升显著。而 maxBytesPerGatheringWrite 的配置通过 EpollChannelConfig.setMaxBytesPerGatheringWrite() 设置，限制单次 writev 的最大字节数，防止大写入阻塞 EventLoop 线程过久。

时序图 ：doWriteMultiple 批量写入的完整链路

八、EpollRecvByteAllocatorHandle：接收缓冲区自适应

EpollRecvByteAllocatorHandle 是 Epoll 传输中接收缓冲区自适应分配的核心，它扩展了 DelegatingHandle 并实现了 ExtendedHandle。其核心设计围绕两个关键点：确保分配 DirectByteBuf（epoll 的 JNI 读取需要直接内存），以及通过 maybeMoreDataToRead() 利用 epoll 水平触发特性判断是否继续读取。

allocate() 方法通过 PreferredDirectByteBufAllocator 确保始终分配直接内存的 ByteBuf：

io.netty.channel.epoll.EpollRecvByteAllocatorHandle#allocate

// 确保分配 DirectByteBuf：epoll 的 JNI 读取需要直接内存
public final ByteBuf allocate(ByteBufAllocator alloc) {
    preferredDirectByteBufAllocator.updateAllocator(alloc);
    return delegate().allocate(preferredDirectByteBufAllocator);
}

maybeMoreDataToRead() 是判断是否继续读取的核心逻辑。其设计思想基于 epoll 水平触发的特性：当 lastBytesRead == attemptedBytesRead 时，说明本次读取填满了分配的缓冲区，socket 接收缓冲区中可能还有剩余数据，需要继续读取：

io.netty.channel.epoll.EpollRecvByteAllocatorHandle

// 利用 epoll 水平触发特性：如果填满了缓冲区，说明可能还有数据
boolean maybeMoreDataToRead() {
    return lastBytesRead() == attemptedBytesRead();
}

continueReading() 覆盖了默认的 maybeMoreDataSupplier，使用 epoll 特有的 maybeMoreDataToRead() 判断逻辑：

io.netty.channel.epoll.EpollRecvByteAllocatorHandle#continueReading

// 使用 epoll 特化的 maybeMoreDataToRead 判断
public final boolean continueReading() {
    return continueReading(defaultMaybeMoreDataSupplier);
}

EpollRecvByteAllocatorStreamingHandle 是流式套接字的扩展版本，覆盖了 maybeMoreDataToRead()，增加了 RDHUP 场景处理------流式套接字收到 RDHUP 后必须执行最后一次"读尽"操作，即使 lastBytesRead < attemptedBytesRead 也要继续读：

io.netty.channel.epoll.EpollRecvByteAllocatorStreamingHandle#maybeMoreDataToRead

// 流式套接字：增加 RDHUP 场景下的"读尽"语义
boolean maybeMoreDataToRead() {
    /**
     * For stream oriented descriptors we can assume we are done reading if the last
     * read attempt didn't produce a full buffer (see Q9 in epoll man).
     *
     * If EPOLLRDHUP has been received we must read until we get a read error.
     */
    return lastBytesRead() == attemptedBytesRead() || isReceivedRdHup();
}

EpollStreamUnsafe.epollInReady() 是 Stream Channel 的读循环，它不断调用 doReadBytes(byteBuf) 读取数据，通过 allocHandle.continueReading() 判断是否继续，利用 EpollRecvByteAllocatorStreamingHandle 的 maybeMoreDataToRead() 逻辑决定是否进行下一轮读取：

io.netty.channel.epoll.AbstractEpollStreamChannel.EpollStreamUnsafe#epollInReady

// Stream Channel 的读循环：利用 maybeMoreDataToRead() 判断是否继续
void epollInReady() {
    final ChannelConfig config = config();
    if (shouldBreakEpollInReady(config)) {
        clearEpollIn0();
        return;
    }
    final EpollRecvByteAllocatorHandle allocHandle = recvBufAllocHandle();
    allocHandle.reset(config);
    ByteBuf byteBuf = null;
    boolean allDataRead = false;
    try {
        do {
            // 分配直接内存 ByteBuf
            byteBuf = allocHandle.allocate(allocator);
            allocHandle.lastBytesRead(doReadBytes(byteBuf));
            if (allocHandle.lastBytesRead() <= 0) {
                byteBuf.release();
                byteBuf = null;
                allDataRead = allocHandle.lastBytesRead() < 0;
                if (allDataRead) {
                    readPending = false;
                }
                break;
            }
            allocHandle.incMessagesRead(1);
            readPending = false;
            pipeline.fireChannelRead(byteBuf);
            byteBuf = null;
            if (shouldBreakEpollInReady(config)) {
                break;
            }
        } while (allocHandle.continueReading()); // maybeMoreDataToRead() 判断

        allocHandle.readComplete();
        pipeline.fireChannelReadComplete();
        if (allDataRead) {
            shutdownInput(true);
        }
    } catch (Throwable t) {
        handleReadException(pipeline, byteBuf, t, allDataRead, allocHandle);
    }
}

与 JDK NIO 的 AdaptiveRecvByteBufAllocator 相比，Epoll 版本通过 maybeMoreDataToRead() 利用 epoll 的批量就绪事件特性，避免了 JDK 版本中需要额外 read() 一次来判断是否还有数据的开销。

时序图 ：EpollStreamUnsafe.epollInReady() 读循环与 maybeMoreDataToRead() 判断

九、EpollChannelOption：Linux 内核独有的 TCP 选项

EpollChannelOption 定义了 Netty 中对 Linux 内核特有 socket 选项的 ChannelOption 常量，底层通过 setsockopt 系统调用设置。这些选项是 Epoll 传输相比 NIO 传输的额外优势，允许应用层精细控制 TCP 协议栈的行为。

EpollChannelOption 中定义的关键选项如下：

io.netty.channel.epoll.EpollChannelOption

// TCP_CORK：延迟发送小数据包，减少网络碎片
public static final ChannelOption<Boolean> TCP_CORK = valueOf(EpollChannelOption.class, "TCP_CORK");

// TCP_NOTSENT_LOWAT：发送缓冲区中未发送数据的最低水位
public static final ChannelOption<Long> TCP_NOTSENT_LOWAT = valueOf(EpollChannelOption.class, "TCP_NOTSENT_LOWAT");

// TCP KeepAlive 参数：空闲时间、探测间隔、探测次数
public static final ChannelOption<Integer> TCP_KEEPIDLE = valueOf(EpollChannelOption.class, "TCP_KEEPIDLE");
public static final ChannelOption<Integer> TCP_KEEPINTVL = valueOf(EpollChannelOption.class, "TCP_KEEPINTVL");
public static final ChannelOption<Integer> TCP_KEEPCNT = valueOf(EpollChannelOption.class, "TCP_KEEPCNT");

// TCP_USER_TIMEOUT：未确认数据超时，强制关闭连接
public static final ChannelOption<Integer> TCP_USER_TIMEOUT =
        valueOf(EpollChannelOption.class, "TCP_USER_TIMEOUT");

// IP_TRANSPARENT：IP 透明代理，允许绑定到非本地 IP
public static final ChannelOption<Boolean> IP_TRANSPARENT = valueOf("IP_TRANSPARENT");

// IP_RECVORIGDSTADDR：接收原始目标地址，用于透明代理
public static final ChannelOption<Boolean> IP_RECVORIGDSTADDR = valueOf("IP_RECVORIGDSTADDR");

// TCP_DEFER_ACCEPT：延迟接受连接，减少无效连接
public static final ChannelOption<Integer> TCP_DEFER_ACCEPT =
        ChannelOption.valueOf(EpollChannelOption.class, "TCP_DEFER_ACCEPT");

// TCP_QUICKACK：启用快速确认，禁用延迟 ACK
public static final ChannelOption<Boolean> TCP_QUICKACK = valueOf(EpollChannelOption.class, "TCP_QUICKACK");

// SO_BUSY_POLL：Socket busy poll 时间（微秒），降低延迟
public static final ChannelOption<Integer> SO_BUSY_POLL = valueOf(EpollChannelOption.class, "SO_BUSY_POLL");

// TCP_MD5SIG：TCP MD5 签名，用于 BGP 等路由协议
public static final ChannelOption<Map<InetAddress, byte[]>> TCP_MD5SIG = valueOf("TCP_MD5SIG");

下面选取三个典型选项进行深入分析：

TCP_CORK （Boolean）：启用后，TCP 会延迟发送小数据包，直到数据积累到一定大小或选项被关闭。这类似于 BSD 平台的 TCP_NOPUSH，适合请求-响应式协议场景。例如，当发送 HTTP 响应时，先启用 TCP_CORK，将响应头和响应体写入 socket，再关闭 TCP_CORK，此时 TCP 协议栈会将积累的数据合并为一个 TCP 段发送，减少网络碎片。

TCP_QUICKACK （Boolean）：启用快速确认模式，禁用 TCP 延迟确认（Delayed ACK）。在默认情况下，TCP 可能会延迟发送 ACK（最多 200ms），以期望将 ACK 与数据合并发送。但在低延迟场景下，这个延迟是不可接受的。TCP_QUICKACK 让 TCP 立即发送 ACK，减少等待时间。

TCP_DEFER_ACCEPT （Integer）：延迟唤醒监听器，直到收到数据才将连接交付给应用层。三次握手仍正常完成，但内核在收到第一个数据包之前不会通知 accept()，因此应用层不会看到未发送数据的空连接。对于 HTTP 等服务，客户端在连接建立后通常会立即发送请求数据，此选项可以避免接受那些仅建立连接但从不发送数据的无效连接，减少资源浪费。

十、整体链路串联：从 EpollIoHandler 到 AbstractEpollUnsafe 的完整闭环

将前文所述的所有组件串联起来，从 EpollIoHandler 的创建到 AbstractEpollUnsafe 的事件处理，形成了完整的 Epoll IO 处理闭环：

1. 工厂创建 ：EpollIoHandler.newFactory() 创建 IoHandlerFactory，在 SingleThreadIoEventLoop 构造中通过 ioHandlerFactory.newHandler(this) 创建 EpollIoHandler 实例。
2. 文件描述符创建 ：openFileDescriptors() 创建 epollFd（epoll 实例）、eventFd（唤醒 fd）、timerFd（定时器 fd），并将 eventFd 和 timerFd 注册到 epoll 实例。
3. Channel 注册 ：register(IoHandle) 方法将 Channel 的 AbstractEpollUnsafe（实现了 EpollIoHandle）注册到 EpollIoHandler，创建 DefaultEpollIoRegistration 并放入 registrations 映射中。注意 epoll_ctl(EPOLL_CTL_ADD) 不在此时调用，而是延迟到 submit() 首次提交 ops 时执行。
4. 事件循环 ：run(IoHandlerContext) 方法通过 selectStrategy 判定策略，选择对应的 epollWait 变体。epollWait() 通过 Native.epollWait() JNI 调用 epoll_wait 系统调用，阻塞等待就绪事件。
5. 事件分发 ：processReady() 遍历 EpollEventArray 中的就绪事件，通过 registrations.get(fd) 获取对应的 DefaultEpollIoRegistration，调用 handle(ev) 分发事件。
6. 事件处理 ：DefaultEpollIoRegistration.handle(ev) 调用 EpollIoHandle.handle(this, eventOf(ev))，最终进入 AbstractEpollUnsafe.handle()，按 EPOLLOUT → EPOLLIN → EPOLLRDHUP 的顺序处理。
7. 批量写入 ：当 EPOLLOUT 就绪时，epollOutReady() 触发 doWrite()，若 msgCount > 1 则走 doWriteMultiple() 路径，通过 IovArray 聚合多个 ByteBuf 为 iovec 数组，调用 socket.writevAddresses() 一次 writev 系统调用完成批量写入。
8. 接收优化 ：当 EPOLLIN 就绪时，epollInReady() 进入读循环，通过 EpollRecvByteAllocatorHandle 分配直接内存 ByteBuf，利用 maybeMoreDataToRead() 判断是否继续读取。

总结 Epoll 传输相比 NIO 传输的四大性能优势：

1. 直接内存事件数组 ：EpollEventArray 避免内核到 Java 堆的数据拷贝，支持 O(1) 索引访问。
2. 批量写入 ：doWriteMultiple + writev 一次系统调用发送多个 ByteBuf，减少上下文切换。
3. 内核级定时器 ：timerfd 融入 epoll_wait 统一监听，无需额外的 ScheduledExecutorService 线程。
4. 轻量级唤醒 ：eventfd 比 Selector.wakeup() 更轻量，nextWakeupNanos 三段式状态机避免重复写。

与 NioIoHandler 的设计对比：NioIoHandler 依赖 JDK Selector 的 selectedKeys 集合（需要 Iterator 遍历或 SelectedSelectionKeySet 数组优化），EpollIoHandler 通过 EpollEventArray 直接内存数组实现 O(1) 索引访问；NioIoHandler 的定时任务依赖 IoHandlerContext.delayNanos() 计算 select(timeout) 的超时时间，EpollIoHandler 通过 timerfd 将定时器转化为文件描述符融入 epoll_wait，超时精度更高且无需每次重新计算。

设计思想凝练为："直接内存 + 批量系统调用 + 内核融合" ------EpollEventArray 通过直接内存避免数据拷贝，doWriteMultiple 通过 writev 批量写入减少系统调用次数，timerfd 和 eventfd 将定时与唤醒统一到 epoll 事件模型中，三项设计将 Linux 内核的能力发挥到极致。

Epoll 传输 vs NIO 传输七维对比表：

维度	Epoll 传输	NIO 传输
事件获取	EpollEventArray 直接内存 + O(1) 索引访问	Selector.selectedKeys() + SelectedSelectionKeySet 数组优化
唤醒机制	eventfd 写入 + nextWakeupNanos 三段式状态机	Selector.wakeup() + AtomicBoolean wakenUp 防重复
定时器	timerfd 融入 epoll_wait 统一监听	IoHandlerContext.delayNanos() 计算 select(timeout) 超时
批量写入	writev 系统调用 + IovArray 直接内存 iovec 数组	SocketChannel.write(ByteBuffer\[\]) JDK gathering write
兴趣管理	DefaultEpollIoRegistration.submit() → epoll_ctl JNI 调用	IoRegistration.submit() → SelectionKey.interestOps()
空轮询修复	无此问题（直接调用 epoll_wait）	SELECTOR_AUTO_REBUILD_THRESHOLD 检测 + rebuildSelector0() 重建
平台兼容	仅 Linux	全平台（JDK NIO 抽象）

从对比表可以看出，Epoll 传输在事件获取、唤醒机制、定时器、批量写入、兴趣管理五个维度上全面优于 NIO 传输：EpollEventArray 直接内存避免了 JDK HashSet 的哈希开销和 Iterator 遍历开销，eventfd + timerfd 将唤醒和定时统一为文件描述符融入 epoll_wait，writev 一次系统调用完成批量写入，epoll_ctl 直接通过 JNI 操作内核。同时，Epoll 传输从底层就避免了 JDK 的空轮询 Bug。NIO 传输的唯一优势在于跨平台兼容性------在所有支持 Java 的平台上提供一致的传输能力。

全文小结

本文聚焦 Netty 4.2 中 Epoll 原生传输的完整实现，从内核机制与 Java 实现两个维度，深入分析了 EpollIoHandler 事件循环、EpollEventArray 直接内存映射、EpollSocketChannel 读写实现、doWriteMultiple 批量写入优化以及 EpollRecvByteAllocatorHandle 接收缓冲区自适应的核心机制。

在内核机制层面，epoll 的 epoll_create/epoll_ctl/epoll_wait 三件套提供了 O(1) 的活跃事件获取能力，eventfd 和 timerfd 将唤醒和定时统一为文件描述符，融入 epoll 事件模型。在可用性检测层面，Epoll.isAvailable() 通过 Native.offsetofEpollData()、Native.newEpollCreate()、Native.newEventFd() 三步 JNI 调用验证 epoll 的可用性，ensureAvailability() 在 EpollIoHandler 初始化块中提供双重保障。在事件循环层面，EpollIoHandler.run() 通过 selectStrategy 策略判定、nextWakeupNanos 三段式状态机、processReady() 的 packed int 返回值，实现了 IO 事件、定时器、唤醒事件的统一调度。在事件抽象层面，EpollIoHandle 和 EpollIoOps 将 epoll 的事件标志封装为位掩码常量，AbstractEpollUnsafe.handle() 按 EPOLLOUT → EPOLLIN → EPOLLRDHUP 的顺序分发事件。在 Channel 实现层面，EpollServerSocketChannel 的 doBind() 和 EpollServerSocketUnsafe 的接受循环，EpollSocketChannel 的 doConnect0() 支持 TFO，构建了完整的连接管理链路。在批量写入层面，doWriteMultiple 通过 IovArray 聚合多个 ByteBuf 为 iovec 数组，writev 一次系统调用完成批量写入，writeBytes 提供单次写入回退。在接收优化层面，EpollRecvByteAllocatorHandle 的 maybeMoreDataToRead() 利用 epoll 水平触发特性判断缓冲区是否还有数据，EpollRecvByteAllocatorStreamingHandle 在 RDHUP 场景下执行最后一次"读尽"操作。

---

原创不易，如果本文对您有帮助，带来了些许灵感或启发，烦请动动小手点赞、关注、转发、收藏。这是作者持续更新的动力源泉，衷心感谢您的支持。我会尽量在工作之余，为大家带来更高品质的内容，努力保持周更。