wepoll 技术文档

1. 安装指南

系统要求

• 操作系统：Windows Vista 或更高版本
• 编译器：近期版本的 MSVC、Clang 或 GCC

安装步骤

1. 从 wepoll GitHub 仓库 下载 wepoll.c 和 wepoll.h 文件。
2. 将这些文件添加到您的项目中。
3. 使用您的编译器编译项目，确保包含 wepoll.c 和 wepoll.h。

2. 项目的使用说明

wepoll 是一个在 Windows 应用程序中实现 epoll API 的库。它快速且可扩展，与 Linux 的 epoll API 行为和接口非常相似。

主要功能

• 支持高效地轮询数以十万计的套接字。
• 全线程安全。
• 多个线程可以轮询同一个 epoll 端口。
• 套接字可以被添加到多个 epoll 集合中。
• 支持 EPOLLIN、EPOLLOUT、EPOLLPRI、EPOLLRDHUP 等所有 epoll 事件。
• 支持边缘触发和单次触发模式。

限制

• 仅适用于套接字。
• 不支持边缘触发 (EPOLLET) 模式。

3. 项目API使用文档

通用说明

• epoll 端口是一个 HANDLE 类型，而不是文件描述符。
• 所有函数在失败时都会设置 errno 和 GetLastError()。

epoll_create/epoll_create1

HANDLE epoll_create(int size);
HANDLE epoll_create1(int flags);

• 创建一个新的 epoll 实例（端口）。
• size 被忽略但必须大于零。
• flags 必须为零，因为没有支持的标志。
• 失败时返回 NULL。

epoll_close

int epoll_close(HANDLE ephnd);

• 关闭一个 epoll 端口。
• 不要尝试使用 close()、CloseHandle() 或 closesocket() 来关闭 epoll 端口。

epoll_ctl

int epoll_ctl(HANDLE ephnd, int op, SOCKET sock, struct epoll_event* event);

• 控制一个 epoll 端口监控的套接字事件。
• ephnd 必须是一个由 epoll_create() 或 epoll_create1() 创建的 HANDLE。
• op 必须是 EPOLL_CTL_ADD、EPOLL_CTL_MOD 或 EPOLL_CTL_DEL 之一。
• sock 必须是一个有效的套接字。
• event 应该指向一个 struct epoll_event。
• 成功返回 0，失败返回 -1。

epoll_wait

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

• 从一个 epoll 端口接收套接字事件。
• events 指向一个调用者分配的 epoll_event 结构数组。
• maxevents 是 events 数组中可以写入的最大事件数。
• timeout 指定在没有事件立即可用时的阻塞行为。
• 返回值：-1 表示错误，0 表示超时，大于等于1 表示存储在 events 缓冲区中的事件数。

struct epoll_event

typedef union epoll_data {
  void* ptr;
  int fd;
  uint32_t u32;
  uint64_t u64;
  SOCKET sock;  /* Windows specific */
  HANDLE hnd;   /* Windows specific */
} epoll_data_t;

struct epoll_event {
  uint32_t events;    /* Epoll 事件和标志 */
  epoll_data_t data;  /* 用户数据变量 */
};

• events 字段是一个包含正在监控/报告的事件和可选标志的位掩码。
• data 字段可以用于将应用程序特定的信息与套接字关联起来。

支持的事件和标志

事件	描述
EPOLLIN	有数据可读，或者有连接就绪接受
EPOLLOUT	可发送数据，或者出站连接成功建立
EPOLLRDHUP	远端发起优雅的套接字关闭
EPOLLPRI	有带外数据可读
EPOLLERR	套接字错误
EPOLLHUP	套接字挂起
EPOLLRDNORM	与 EPOLLIN 相同
EPOLLRDBAND	与 EPOLLPRI 相同
EPOLLWRNORM	与 EPOLLOUT 相同
EPOLLWRBAND	与 EPOLLOUT 相同
EPOLLMSG	从不报告

标志	描述
EPOLLONESHOT	只报告一次事件
EPOLLET	不支持
EPOLLEXCLUSIVE	不支持
EPOLLWAKEUP	不支持

4. 项目安装方式

请参考上述的“安装指南”部分。