{"id":15622047,"url":"https://github.com/piscisaureus/wepoll","last_synced_at":"2025-05-16T11:04:42.885Z","repository":{"id":4410288,"uuid":"5547802","full_name":"piscisaureus/wepoll","owner":"piscisaureus","description":"wepoll: fast epoll for windows⁧  🎭","archived":false,"fork":false,"pushed_at":"2024-07-22T22:43:54.000Z","size":675,"stargazers_count":997,"open_issues_count":10,"forks_count":156,"subscribers_count":53,"default_branch":"dist","last_synced_at":"2025-04-09T05:05:16.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piscisaureus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-08-25T02:06:20.000Z","updated_at":"2025-04-04T20:54:26.000Z","dependencies_parsed_at":"2024-10-22T21:31:39.176Z","dependency_job_id":null,"html_url":"https://github.com/piscisaureus/wepoll","commit_stats":{"total_commits":521,"total_committers":2,"mean_commits":260.5,"dds":"0.0019193857965451588","last_synced_commit":"0598a791bf9cbbf480793d778930fc635b044980"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piscisaureus%2Fwepoll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piscisaureus%2Fwepoll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piscisaureus%2Fwepoll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piscisaureus%2Fwepoll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piscisaureus","download_url":"https://codeload.github.com/piscisaureus/wepoll/tar.gz/refs/heads/dist","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518384,"owners_count":22084374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T09:52:40.536Z","updated_at":"2025-05-16T11:04:37.875Z","avatar_url":"https://github.com/piscisaureus.png","language":"C","funding_links":[],"categories":["Networking","C"],"sub_categories":[],"readme":"# wepoll - epoll for windows\n\n[![][ci status badge]][ci status link]\n\nThis library implements the [epoll][man epoll] API for Windows\napplications. It is fast and scalable, and it closely resembles the API\nand behavior of Linux' epoll.\n\n## Rationale\n\nUnlike Linux, OS X, and many other operating systems, Windows doesn't\nhave a good API for receiving socket state notifications. It only\nsupports the `select` and `WSAPoll` APIs, but they\n[don't scale][select scale] and suffer from\n[other issues][wsapoll broken].\n\nUsing I/O completion ports isn't always practical when software is\ndesigned to be cross-platform. Wepoll offers an alternative that is\nmuch closer to a drop-in replacement for software that was designed\nto run on Linux.\n\n## Features\n\n* Can poll 100000s of sockets efficiently.\n* Fully thread-safe.\n* Multiple threads can poll the same epoll port.\n* Sockets can be added to multiple epoll sets.\n* All epoll events (`EPOLLIN`, `EPOLLOUT`, `EPOLLPRI`, `EPOLLRDHUP`)\n  are supported.\n* Level-triggered and one-shot (`EPOLLONESTHOT`) modes are supported\n* Trivial to embed: you need [only two files][dist].\n\n## Limitations\n\n* Only works with sockets.\n* Edge-triggered (`EPOLLET`) mode isn't supported.\n\n## How to use\n\nThe library is [distributed][dist] as a single source file\n([wepoll.c][wepoll.c]) and a single header file ([wepoll.h][wepoll.h]).\u003cbr\u003e\nCompile the .c file as part of your project, and include the header wherever\nneeded.\n\n## Compatibility\n\n* Requires Windows Vista or higher.\n* Can be compiled with recent versions of MSVC, Clang, and GCC.\n\n## API\n\n### General remarks\n\n* The epoll port is a `HANDLE`, not a file descriptor.\n* All functions set both `errno` and `GetLastError()` on failure.\n* For more extensive documentation, see the [epoll(7) man page][man epoll],\n  and the per-function man pages that are linked below.\n\n### epoll_create/epoll_create1\n\n```c\nHANDLE epoll_create(int size);\nHANDLE epoll_create1(int flags);\n```\n\n* Create a new epoll instance (port).\n* `size` is ignored but most be greater than zero.\n* `flags` must be zero as there are no supported flags.\n* Returns `NULL` on failure.\n* [Linux man page][man epoll_create]\n\n### epoll_close\n\n```c\nint epoll_close(HANDLE ephnd);\n```\n\n* Close an epoll port.\n* Do not attempt to close the epoll port with `close()`,\n  `CloseHandle()` or `closesocket()`.\n\n### epoll_ctl\n\n```c\nint epoll_ctl(HANDLE ephnd,\n              int op,\n              SOCKET sock,\n              struct epoll_event* event);\n```\n\n* Control which socket events are monitored by an epoll port.\n* `ephnd` must be a HANDLE created by\n  [`epoll_create()`](#epoll_createepoll_create1) or\n  [`epoll_create1()`](#epoll_createepoll_create1).\n* `op` must be one of `EPOLL_CTL_ADD`, `EPOLL_CTL_MOD`, `EPOLL_CTL_DEL`.\n* `sock` must be a valid socket created by [`socket()`][msdn socket],\n  [`WSASocket()`][msdn wsasocket], or [`accept()`][msdn accept].\n* `event` should be a pointer to a [`struct epoll_event`](#struct-epoll_event).\u003cbr\u003e\n  If `op` is `EPOLL_CTL_DEL` then the `event` parameter is ignored, and it\n  may be `NULL`.\n* Returns 0 on success, -1 on failure.\n* It is recommended to always explicitly remove a socket from its epoll\n  set using `EPOLL_CTL_DEL` *before* closing it.\u003cbr\u003e\n  As on Linux, closed sockets are automatically removed from the epoll set, but\n  wepoll may not be able to detect that a socket was closed until the next call\n  to [`epoll_wait()`](#epoll_wait).\n* [Linux man page][man epoll_ctl]\n\n### epoll_wait\n\n```c\nint epoll_wait(HANDLE ephnd,\n               struct epoll_event* events,\n               int maxevents,\n               int timeout);\n```\n\n* Receive socket events from an epoll port.\n* `events` should point to a caller-allocated array of\n  [`epoll_event`](#struct-epoll_event) structs, which will receive the\n  reported events.\n* `maxevents` is the maximum number of events that will be written to the\n  `events` array, and must be greater than zero.\n* `timeout` specifies whether to block when no events are immediately available.\n  - `\u003c0` block indefinitely\n  - `0`  report any events that are already waiting, but don't block\n  - `≥1` block for at most N milliseconds\n* Return value:\n  - `-1` an error occurred\n  - `0`  timed out without any events to report\n  - `≥1` the number of events stored in the `events` buffer\n* [Linux man page][man epoll_wait]\n\n### struct epoll_event\n\n```c\ntypedef union epoll_data {\n  void* ptr;\n  int fd;\n  uint32_t u32;\n  uint64_t u64;\n  SOCKET sock;        /* Windows specific */\n  HANDLE hnd;         /* Windows specific */\n} epoll_data_t;\n```\n\n```c\nstruct epoll_event {\n  uint32_t events;    /* Epoll events and flags */\n  epoll_data_t data;  /* User data variable */\n};\n```\n\n* The `events` field is a bit mask containing the events being\n  monitored/reported, and optional flags.\u003cbr\u003e\n  Flags are accepted by [`epoll_ctl()`](#epoll_ctl), but they are not reported\n  back by [`epoll_wait()`](#epoll_wait).\n* The `data` field can be used to associate application-specific information\n  with a socket; its value will be returned unmodified by\n  [`epoll_wait()`](#epoll_wait).\n* [Linux man page][man epoll_ctl]\n\n| Event         | Description                                                          |\n|---------------|----------------------------------------------------------------------|\n| `EPOLLIN`     | incoming data available, or incoming connection ready to be accepted |\n| `EPOLLOUT`    | ready to send data, or outgoing connection successfully established  |\n| `EPOLLRDHUP`  | remote peer initiated graceful socket shutdown                       |\n| `EPOLLPRI`    | out-of-band data available for reading                               |\n| `EPOLLERR`    | socket error\u003csup\u003e1\u003c/sup\u003e                                             |\n| `EPOLLHUP`    | socket hang-up\u003csup\u003e1\u003c/sup\u003e                                           |\n| `EPOLLRDNORM` | same as `EPOLLIN`                                                    |\n| `EPOLLRDBAND` | same as `EPOLLPRI`                                                   |\n| `EPOLLWRNORM` | same as `EPOLLOUT`                                                   |\n| `EPOLLWRBAND` | same as `EPOLLOUT`                                                   |\n| `EPOLLMSG`    | never reported                                                       |\n\n| Flag             | Description               |\n|------------------|---------------------------|\n| `EPOLLONESHOT`   | report event(s) only once |\n| `EPOLLET`        | not supported by wepoll   |\n| `EPOLLEXCLUSIVE` | not supported by wepoll   |\n| `EPOLLWAKEUP`    | not supported by wepoll   |\n\n\u003csup\u003e1\u003c/sup\u003e: the `EPOLLERR` and `EPOLLHUP` events may always be reported by\n[`epoll_wait()`](#epoll_wait), regardless of the event mask that was passed to\n[`epoll_ctl()`](#epoll_ctl).\n\n\n[ci status badge]:  https://ci.appveyor.com/api/projects/status/github/piscisaureus/wepoll?branch=master\u0026svg=true\n[ci status link]:   https://ci.appveyor.com/project/piscisaureus/wepoll/branch/master\n[dist]:             https://github.com/piscisaureus/wepoll/tree/dist\n[man epoll]:        http://man7.org/linux/man-pages/man7/epoll.7.html\n[man epoll_create]: http://man7.org/linux/man-pages/man2/epoll_create.2.html\n[man epoll_ctl]:    http://man7.org/linux/man-pages/man2/epoll_ctl.2.html\n[man epoll_wait]:   http://man7.org/linux/man-pages/man2/epoll_wait.2.html\n[msdn accept]:      https://msdn.microsoft.com/en-us/library/windows/desktop/ms737526(v=vs.85).aspx\n[msdn socket]:      https://msdn.microsoft.com/en-us/library/windows/desktop/ms740506(v=vs.85).aspx\n[msdn wsasocket]:   https://msdn.microsoft.com/en-us/library/windows/desktop/ms742212(v=vs.85).aspx\n[select scale]:     https://daniel.haxx.se/docs/poll-vs-select.html\n[wsapoll broken]:   https://daniel.haxx.se/blog/2012/10/10/wsapoll-is-broken/\n[wepoll.c]:         https://github.com/piscisaureus/wepoll/blob/dist/wepoll.c\n[wepoll.h]:         https://github.com/piscisaureus/wepoll/blob/dist/wepoll.h\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiscisaureus%2Fwepoll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiscisaureus%2Fwepoll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiscisaureus%2Fwepoll/lists"}