version 1.5.8

Although the header files included in the official Windows SDK have
mixed case file names, MinGW opted to ship headers with entirely lower
case names.

Since the MinGW headers are often used when cross compiling Windows
binaries on Linux hosts, and Linux treats paths as case sensitive by
default, following the 'official' spelling breaks many cross build
setups.

Non-cross builds do not seem to be affected by using lower case file
names, and Microsoft also does not seem particularly consistent in the
way it spells header file names in e.g. documentation and sample code.

Therefore, this patch makes wepoll use lower case file names when
including Windows headers, regardless of whether MinGW or the official
SDK is used.

See also https://github.com/libevent/libevent/pull/1039
and https://github.com/stjepang/smol/issues/138.

Closes: https://github.com/piscisaureus/wepoll/pull/19

LICENSE

@@ -0,0 +1,28 @@
+wepoll - epoll for Windows
+https://github.com/piscisaureus/wepoll
+
+Copyright 2012-2020, Bert Belder <bertbelder@gmail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,18 +1,18 @@
 # wepoll - epoll for windows
 
-This library implements the
+[![][ci status badge]][ci status link]
-[epoll](http://man7.org/linux/man-pages/man7/epoll.7.html) API for
+
-Windows applications. It attempts to be efficient, and to match the
+This library implements the [epoll][man epoll] API for Windows
-Linux API and as closely as possible.
+applications. It is fast and scalable, and it closely resembles the API
+and behavior of Linux' epoll.
 
 ## 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](https://daniel.haxx.se/docs/poll-vs-select.html)
+[don't scale][select scale] and suffer from
-and suffer from
+[other issues][wsapoll broken].
-[other issues](https://daniel.haxx.se/blog/2012/10/10/wsapoll-is-broken/).
 
 Using I/O completion ports isn't always practical when software is
 designed to be cross-platform. Wepoll offers an alternative that is
@@ -21,37 +21,40 @@ to run on Linux.
 
 ## Features
 
-* can poll 100000s of sockets efficiently
+* Can poll 100000s of sockets efficiently.
-* fully thread safe
+* Fully thread-safe.
-* multiple threads can poll the same epoll port
+* Multiple threads can poll the same epoll port.
-* sockets can be added to multiple epoll sets
+* Sockets can be added to multiple epoll sets.
-* polling for `EPOLLIN`, `EPOLLOUT`, `EPOLLPRI`, `EPOLLRDHUP`,
+* All epoll events (`EPOLLIN`, `EPOLLOUT`, `EPOLLPRI`, `EPOLLRDHUP`)
-  `EPOLLHUP`, and `EPOLLERR` events
+  are supported.
-* `EPOLLONESTHOT` flag
+* Level-triggered and one-shot (`EPOLLONESTHOT`) modes are supported
+* Trivial to embed: you need [only two files][dist].
 
 ## Limitations
 
-* only works with sockets
+* Only works with sockets.
-* some modes not suported: `EPOLLET`, `EPOLLEXCLUSIVE`
+* Edge-triggered (`EPOLLET`) mode isn't supported.
 
 ## How to use
 
-The library is distributed as a single source file (wepoll.c) and a
+The library is [distributed][dist] as a single source file
-single header file (wepoll.h). Compile the .c file as part of your
+([wepoll.c][wepoll.c]) and a single header file ([wepoll.h][wepoll.h]).<br>
-project, and include the header wherever needed.
+Compile the .c file as part of your project, and include the header wherever
+needed.
 
 ## Compatibility
 
-* Requires Windows 7 or higher.
+* Requires Windows Vista or higher.
-* Can be compiled with recent versions of MSVC and Clang.
+* Can be compiled with recent versions of MSVC, Clang, and GCC.
-* GCC (mingw) should work (but is untested).
 
-## API notes
+## API
 
-### General
+### General remarks
 
 * The epoll port is a `HANDLE`, not a file descriptor.
 * All functions set both `errno` and `GetLastError()` on failure.
+* For more extensive documentation, see the [epoll(7) man page][man epoll],
+  and the per-function man pages that are linked below.
 
 ### epoll_create/epoll_create1
 
@@ -61,10 +64,10 @@ HANDLE epoll_create1(int flags);
 ```
 
 * Create a new epoll instance (port).
-* `size` is ignored but most be nonzero.
+* `size` is ignored but most be greater than zero.
 * `flags` must be zero as there are no supported flags.
-* Returns `INVALID_HANDLE_VALUE` on failure.
+* Returns `NULL` on failure.
-* [man page](http://man7.org/linux/man-pages/man2/epoll_create.2.html)
+* [Linux man page][man epoll_create]
 
 ### epoll_close
 
@@ -86,15 +89,22 @@ int epoll_ctl(HANDLE ephnd,
 ```
 
 * Control which socket events are monitored by an epoll port.
-* `ephnd` must be a HANDLE created by `epoll_create` or `epoll_create1`.
+* `ephnd` must be a HANDLE created by
+  [`epoll_create()`](#epoll_createepoll_create1) or
+  [`epoll_create1()`](#epoll_createepoll_create1).
 * `op` must be one of `EPOLL_CTL_ADD`, `EPOLL_CTL_MOD`, `EPOLL_CTL_DEL`.
+* `sock` must be a valid socket created by [`socket()`][msdn socket],
+  [`WSASocket()`][msdn wsasocket], or [`accept()`][msdn accept].
+* `event` should be a pointer to a [`struct epoll_event`](#struct-epoll_event).<br>
+  If `op` is `EPOLL_CTL_DEL` then the `event` parameter is ignored, and it
+  may be `NULL`.
+* Returns 0 on success, -1 on failure.
 * It is recommended to always explicitly remove a socket from its epoll
-  set using `EPOLL_CTL_MOD` *before* closing it. As on Linux, sockets
+  set using `EPOLL_CTL_DEL` *before* closing it.<br>
-  are automatically removed from the epoll set when they are closed, but
+  As on Linux, closed sockets are automatically removed from the epoll set, but
-  wepoll may not be able to detect this until the next call to
+  wepoll may not be able to detect that a socket was closed until the next call
-  `epoll_wait()`.
+  to [`epoll_wait()`](#epoll_wait).
-* TODO: expand
+* [Linux man page][man epoll_ctl]
-* [man page](http://man7.org/linux/man-pages/man2/epoll_ctl.2.html)
 
 ### epoll_wait
 
@@ -106,10 +116,87 @@ int epoll_wait(HANDLE ephnd,
 ```
 
 * Receive socket events from an epoll port.
-* Returns
+* `events` should point to a caller-allocated array of
-  - -1 on failure
+  [`epoll_event`](#struct-epoll_event) structs, which will receive the
-  - 0 when a timeout occurs
+  reported events.
-  - \>0 the number of evens received
+* `maxevents` is the maximum number of events that will be written to the
-* TODO: expand
+  `events` array, and must be greater than zero.
-* [man page](http://man7.org/linux/man-pages/man2/epoll_wait.2.html)
+* `timeout` specifies whether to block when no events are immediately available.
+  - `<0` block indefinitely
+  - `0`  report any events that are already waiting, but don't block
+  - `≥1` block for at most N milliseconds
+* Return value:
+  - `-1` an error occurred
+  - `0`  timed out without any events to report
+  - `≥1` the number of events stored in the `events` buffer
+* [Linux man page][man epoll_wait]
 
+### struct epoll_event
+
+```c
+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;
+```
+
+```c
+struct epoll_event {
+  uint32_t events;    /* Epoll events and flags */
+  epoll_data_t data;  /* User data variable */
+};
+```
+
+* The `events` field is a bit mask containing the events being
+  monitored/reported, and optional flags.<br>
+  Flags are accepted by [`epoll_ctl()`](#epoll_ctl), but they are not reported
+  back by [`epoll_wait()`](#epoll_wait).
+* The `data` field can be used to associate application-specific information
+  with a socket; its value will be returned unmodified by
+  [`epoll_wait()`](#epoll_wait).
+* [Linux man page][man epoll_ctl]
+
+| Event         | Description                                                          |
+|---------------|----------------------------------------------------------------------|
+| `EPOLLIN`     | incoming data available, or incoming connection ready to be accepted |
+| `EPOLLOUT`    | ready to send data, or outgoing connection successfully established  |
+| `EPOLLRDHUP`  | remote peer initiated graceful socket shutdown                       |
+| `EPOLLPRI`    | out-of-band data available for reading                               |
+| `EPOLLERR`    | socket error<sup>1</sup>                                             |
+| `EPOLLHUP`    | socket hang-up<sup>1</sup>                                           |
+| `EPOLLRDNORM` | same as `EPOLLIN`                                                    |
+| `EPOLLRDBAND` | same as `EPOLLPRI`                                                   |
+| `EPOLLWRNORM` | same as `EPOLLOUT`                                                   |
+| `EPOLLWRBAND` | same as `EPOLLOUT`                                                   |
+| `EPOLLMSG`    | never reported                                                       |
+
+| Flag             | Description               |
+|------------------|---------------------------|
+| `EPOLLONESHOT`   | report event(s) only once |
+| `EPOLLET`        | not supported by wepoll   |
+| `EPOLLEXCLUSIVE` | not supported by wepoll   |
+| `EPOLLWAKEUP`    | not supported by wepoll   |
+
+<sup>1</sup>: the `EPOLLERR` and `EPOLLHUP` events may always be reported by
+[`epoll_wait()`](#epoll_wait), regardless of the event mask that was passed to
+[`epoll_ctl()`](#epoll_ctl).
+
+
+[ci status badge]:  https://ci.appveyor.com/api/projects/status/github/piscisaureus/wepoll?branch=master&svg=true
+[ci status link]:   https://ci.appveyor.com/project/piscisaureus/wepoll/branch/master
+[dist]:             https://github.com/piscisaureus/wepoll/tree/dist
+[man epoll]:        http://man7.org/linux/man-pages/man7/epoll.7.html
+[man epoll_create]: http://man7.org/linux/man-pages/man2/epoll_create.2.html
+[man epoll_ctl]:    http://man7.org/linux/man-pages/man2/epoll_ctl.2.html
+[man epoll_wait]:   http://man7.org/linux/man-pages/man2/epoll_wait.2.html
+[msdn accept]:      https://msdn.microsoft.com/en-us/library/windows/desktop/ms737526(v=vs.85).aspx
+[msdn socket]:      https://msdn.microsoft.com/en-us/library/windows/desktop/ms740506(v=vs.85).aspx
+[msdn wsasocket]:   https://msdn.microsoft.com/en-us/library/windows/desktop/ms742212(v=vs.85).aspx
+[select scale]:     https://daniel.haxx.se/docs/poll-vs-select.html
+[wsapoll broken]:   https://daniel.haxx.se/blog/2012/10/10/wsapoll-is-broken/
+[wepoll.c]:         https://github.com/piscisaureus/wepoll/blob/dist/wepoll.c
+[wepoll.h]:         https://github.com/piscisaureus/wepoll/blob/dist/wepoll.h

wepoll.h

@@ -1,9 +1,9 @@
 /*
  * wepoll - epoll for Windows
- * Copyright 2012-2017, Bert Belder. All rights reserved.
+ * https://github.com/piscisaureus/wepoll
  *
- * The red-black tree implementation:
+ * Copyright 2012-2020, Bert Belder <bertbelder@gmail.com>
- * Copyright 2002 Niels Provos <provos@citi.umich.edu> All rights reserved.
+ * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
@@ -39,32 +39,32 @@
 #include <stdint.h>
 
 enum EPOLL_EVENTS {
-  EPOLLIN = 1 << 0,
+  EPOLLIN      = (int) (1U <<  0),
-  EPOLLPRI = 1 << 1,
+  EPOLLPRI     = (int) (1U <<  1),
-  EPOLLOUT = 1 << 2,
+  EPOLLOUT     = (int) (1U <<  2),
-  EPOLLERR = 1 << 3,
+  EPOLLERR     = (int) (1U <<  3),
-  EPOLLHUP = 1 << 4,
+  EPOLLHUP     = (int) (1U <<  4),
-  EPOLLRDNORM = 1 << 6,
+  EPOLLRDNORM  = (int) (1U <<  6),
-  EPOLLRDBAND = 1 << 7,
+  EPOLLRDBAND  = (int) (1U <<  7),
-  EPOLLWRNORM = 1 << 8,
+  EPOLLWRNORM  = (int) (1U <<  8),
-  EPOLLWRBAND = 1 << 9,
+  EPOLLWRBAND  = (int) (1U <<  9),
-  EPOLLMSG = 1 << 10,
+  EPOLLMSG     = (int) (1U << 10), /* Never reported. */
-  EPOLLRDHUP = 1 << 13,
+  EPOLLRDHUP   = (int) (1U << 13),
-  EPOLLONESHOT = 1 << 31
+  EPOLLONESHOT = (int) (1U << 31)
 };
 
-#define EPOLLIN EPOLLIN
+#define EPOLLIN      (1U <<  0)
-#define EPOLLPRI EPOLLPRI
+#define EPOLLPRI     (1U <<  1)
-#define EPOLLOUT EPOLLOUT
+#define EPOLLOUT     (1U <<  2)
-#define EPOLLERR EPOLLERR
+#define EPOLLERR     (1U <<  3)
-#define EPOLLHUP EPOLLHUP
+#define EPOLLHUP     (1U <<  4)
-#define EPOLLRDNORM EPOLLRDNORM
+#define EPOLLRDNORM  (1U <<  6)
-#define EPOLLRDBAND EPOLLRDBAND
+#define EPOLLRDBAND  (1U <<  7)
-#define EPOLLWRNORM EPOLLWRNORM
+#define EPOLLWRNORM  (1U <<  8)
-#define EPOLLWRBAND EPOLLWRBAND
+#define EPOLLWRBAND  (1U <<  9)
-#define EPOLLMSG EPOLLMSG
+#define EPOLLMSG     (1U << 10)
-#define EPOLLRDHUP EPOLLRDHUP
+#define EPOLLRDHUP   (1U << 13)
-#define EPOLLONESHOT EPOLLONESHOT
+#define EPOLLONESHOT (1U << 31)
 
 #define EPOLL_CTL_ADD 1
 #define EPOLL_CTL_MOD 2
@@ -78,12 +78,12 @@ typedef union epoll_data {
   int fd;
   uint32_t u32;
   uint64_t u64;
-  SOCKET sock;
+  SOCKET sock; /* Windows specific */
-  HANDLE hnd;
+  HANDLE hnd;  /* Windows specific */
 } epoll_data_t;
 
 struct epoll_event {
-  uint32_t events;   /* Epoll events */
+  uint32_t events;   /* Epoll events and flags */
   epoll_data_t data; /* User data variable */
 };