wepoll/README.md

wepoll - epoll for windows

This library implements the epoll API for Windows applications. It attempts to be efficient, and to match the Linux API as semantics as closely as possible.

Rationale

Unlike Linux, OS X, and many other operating systems, Windows doesn't have a good API for receiving socket state notifications. It only supports the select and WSAPoll APIs, but they don't scale and suffer from other issues.

Using I/O completion ports isn't always practical when software is designed to be cross-platform. Wepoll offers an alternative that is much closer to a drop-in replacement for software that was designed to run on Linux.

Features

• can poll 100000s of sockets efficiently
• fully thread safe
• multiple threads can poll the same epoll port
• sockets can be added to multiple epoll sets
• polling for EPOLLIN, EPOLLOUT, EPOLLPRI, EPOLLRDHUP, EPOLLHUP, and EPOLLERR events
• EPOLLONESTHOT flag

Limitations

• only works with sockets
• some modes not suported: EPOLLET, EPOLLEXCLUSIVE

How to use

The library is distributed as a single source file (wepoll.c) and a single header file (wepoll.h). Compile the .c file as part of your project, and include the header wherever needed.

Compatibility

• Requires Windows 7 or higher.
• Can be compiled with recent versions of MSVC and Clang.
• GCC (mingw) should work (but is untested).

API notes

General

• The epoll port is a HANDLE, not a file descriptor.
• All functions set both errno and GetLastError() on failure.

epoll_create/epoll_create1

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

• Create a new epoll instance (port).
• size is ignored but most be greater than zero.
• flags must be zero as there are no supported flags.
• Returns NULL on failure.
• man page

epoll_close

int epoll_close(HANDLE ephnd);

• Close an epoll port.
• Do not attempt to close the epoll port with close(), CloseHandle() or closesocket().

epoll_ctl

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

• Control which socket events are monitored by an epoll port.
• ephnd must be a HANDLE created by epoll_create or epoll_create1.
• op must be one of EPOLL_CTL_ADD, EPOLL_CTL_MOD, EPOLL_CTL_DEL.
• It is recommended to always explicitly remove a socket from its epoll set using EPOLL_CTL_DEL before closing it. As on Linux, sockets are automatically removed from the epoll set when they are closed, but wepoll may not be able to detect this until the next call to epoll_wait().
• TODO: expand
• man page

epoll_wait

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

• Receive socket events from an epoll port.
• Returns
  • -1 on failure
  • 0 when a timeout occurs
  • ≥1 the number of evens received
• TODO: expand
• man page