[ViewVC] Diff of: cvs/libev/ev.3

Comparing libev/ev.3 (file contents):
Revision 1.108 by root, Sat Jul 28 04:15:15 2018 UTC vs.
Revision 1.112 by root, Sun Jun 23 23:27:34 2019 UTC

-.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
+.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .\"
 .\" Escape single quotes in literal strings from groff's Unicode transform.
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" If the F register is >0, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .\"
 .\" Avoid warning from groff about undefined register 'F'.
 .de IX
 ..
 .nr rF 0
 .if \n(.g .if rF .nr rF 1
-.if (\n(rF:(\n(.g==0)) \{
+.if (\n(rF:(\n(.g==0)) \{\
-.    if \nF \{
+.    if \nF \{\
 .        de IX
 .        tm Index:\\$1\t\\n%\t"\\$2"
 ..
-.        if !\nF==2 \{
+.        if !\nF==2 \{\
 .            nr % 0
 .            nr F 2
 .        \}
 .    \}
 .\}
 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2017-11-14" "libev-4.24" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2019-06-23" "libev-4.25" "libev - high performance full featured event loop"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 watchers\fR, which are relatively small C structures you initialise with the
 details of the event, and then hand it over to libev by \fIstarting\fR the
 watcher.
 .SS "\s-1FEATURES\s0"
 .IX Subsection "FEATURES"
-Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the
+Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific aio and \f(CW\*(C`epoll\*(C'\fR
-BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms
+interfaces, the BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port
-for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface
+mechanisms for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR
-(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner
+interface (for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner
 inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative
 timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling
 (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status
 change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event
 loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
 .Sp
 You could override this function in high-availability programs to, say,
 free some memory if it cannot allocate memory, to use a special allocator,
 or even to sleep a while and retry until some memory is available.
 .Sp
+Example: The following is the \f(CW\*(C`realloc\*(C'\fR function that libev itself uses
+which should work with \f(CW\*(C`realloc\*(C'\fR and \f(CW\*(C`free\*(C'\fR functions of all kinds and
+is probably a good basis for your own implementation.
+.Sp
+.Vb 5
+\&   static void *
+\&   ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
+\&   {
+\&     if (size)
+\&       return realloc (ptr, size);
+\&
+\&     free (ptr);
+\&     return 0;
+\&   }
+.Ve
+.Sp
 Example: Replace the libev allocator with one that waits a bit and then
-retries (example requires a standards-compliant \f(CW\*(C`realloc\*(C'\fR).
+retries.
 .Sp
-.Vb 6
+.Vb 8
 \&   static void *
 \&   persistent_realloc (void *ptr, size_t size)
 \&   {
+\&     if (!size)
+\&       {
+\&         free (ptr);
+\&         return 0;
+\&       }
+\&
 \&     for (;;)
 \&       {
 \&         void *newptr = realloc (ptr, size);
 \&
 \&         if (newptr)
 .Sp
 This flag's behaviour will become the default in future versions of libev.
 .ie n .IP """EVBACKEND_SELECT""  (value 1, portable select backend)" 4
 .el .IP "\f(CWEVBACKEND_SELECT\fR  (value 1, portable select backend)" 4
 .IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
-This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
+This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
 libev tries to roll its own fd_set with no limits on the number of fds,
 but if that fails, expect a fairly low limit on the number of fds when
 using this backend. It doesn't scale too well (O(highest_fd)), but its
 usually the fastest backend for a low number of (low-numbered :) fds.
 .Sp
 \&\f(CW\*(C`writefds\*(C'\fR set (and to work around Microsoft Windows bugs, also onto the
 \&\f(CW\*(C`exceptfds\*(C'\fR set on that platform).
 .ie n .IP """EVBACKEND_POLL""    (value 2, poll backend, available everywhere except on windows)" 4
 .el .IP "\f(CWEVBACKEND_POLL\fR    (value 2, poll backend, available everywhere except on windows)" 4
 .IX Item "EVBACKEND_POLL (value 2, poll backend, available everywhere except on windows)"
-And this is your standard \fIpoll\fR\|(2) backend. It's more complicated
+And this is your standard \fBpoll\fR\|(2) backend. It's more complicated
 than select, but handles sparse fds better and has no artificial
 limit on the number of fds you can use (except it will slow down
 considerably with a lot of inactive fds). It scales similarly to select,
 i.e. O(total_fds). See the entry for \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR, above, for
 performance tips.
 This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
 \&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
 .ie n .IP """EVBACKEND_EPOLL""   (value 4, Linux)" 4
 .el .IP "\f(CWEVBACKEND_EPOLL\fR   (value 4, Linux)" 4
 .IX Item "EVBACKEND_EPOLL (value 4, Linux)"
-Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
+Use the linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
 kernels).
 .Sp
 For few fds, this backend is a bit little slower than poll and select, but
 it scales phenomenally better. While poll and select usually scale like
 O(total_fds) where total_fds is the total number of fds (or the highest
 All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
 faster than epoll for maybe up to a hundred file descriptors, depending on
 the usage. So sad.
 .Sp
 While nominally embeddable in other event loops, this feature is broken in
-all kernel versions tested so far.
+a lot of kernel revisions, but probably(!) works in current versions.
+.Sp
+This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
+\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
+.ie n .IP """EVBACKEND_LINUXAIO""   (value 64, Linux)" 4
+.el .IP "\f(CWEVBACKEND_LINUXAIO\fR   (value 64, Linux)" 4
+.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
+Use the linux-specific linux aio (\fInot\fR \f(CWaio(7)\fR but \f(CWio_submit(2)\fR) event interface available in post\-4.18 kernels.
+.Sp
+If this backend works for you (as of this writing, it was very
+experimental), it is the best event interface available on linux and might
+be well worth enabling it \- if it isn't available in your kernel this will
+be detected and this backend will be skipped.
+.Sp
+This backend can batch oneshot requests and supports a user-space ring
+buffer to receive events. It also doesn't suffer from most of the design
+problems of epoll (such as not being able to remove event sources from
+the epoll set), and generally sounds too good to be true. Because, this
+being the linux kernel, of course it suffers from a whole new set of
+limitations.
+.Sp
+For one, it is not easily embeddable (but probably could be done using
+an event fd at some extra overhead). It also is subject to a system wide
+limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR \- each loop
+currently requires \f(CW61\fR of this number. If no aio requests are left, this
+backend will be skipped during initialisation.
+.Sp
+Most problematic in practise, however, is that not all file descriptors
+work with it. For example, in linux 5.1, tcp sockets, pipes, event fds,
+files, \fI/dev/null\fR and a few others are supported, but ttys do not work
+(probably because of a bug), so this is not (yet?) a generic event polling
+interface.
+.Sp
+To work around this latter problem, the current version of libev uses
+epoll as a fallback for file deescriptor types that do not work. Epoll
+is used in, kind of, slow mode that hopefully avoids most of its design
+problems and requires 1\-3 extra syscalls per active fd every iteration.
 .Sp
 This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
 \&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
 .ie n .IP """EVBACKEND_KQUEUE""  (value 8, most \s-1BSD\s0 clones)" 4
 .el .IP "\f(CWEVBACKEND_KQUEUE\fR  (value 8, most \s-1BSD\s0 clones)" 4
 Example: Use whatever libev has to offer, but make sure that kqueue is
 used if available.
 .Sp
 .Vb 1
 \&   struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
+.Ve
+.Sp
+Example: Similarly, on linux, you mgiht want to take advantage of the
+linux aio backend if possible, but fall back to something else if that
+isn't available.
+.Sp
+.Vb 1
+\&   struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
 .Ve
 .RE
 .IP "ev_loop_destroy (loop)" 4
 .IX Item "ev_loop_destroy (loop)"
 Destroys an event loop object (frees all memory and kernel state
 bug in your program.
 .Sp
 Libev will usually signal a few \*(L"dummy\*(R" events together with an error, for
 example it might indicate that a fd is readable or writable, and if your
 callbacks is well-written it can just attempt the operation and cope with
-the error from \fIread()\fR or \fIwrite()\fR. This will not work in multi-threaded
+the error from \fBread()\fR or \fBwrite()\fR. This will not work in multi-threaded
 programs, though, as the fd could already be closed and reused for another
 thing, so beware.
 .SS "\s-1GENERIC WATCHER FUNCTIONS\s0"
 .IX Subsection "GENERIC WATCHER FUNCTIONS"
 .ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
 But really, best use non-blocking mode.
 .PP
 \fIThe special problem of disappearing file descriptors\fR
 .IX Subsection "The special problem of disappearing file descriptors"
 .PP
-Some backends (e.g. kqueue, epoll) need to be told about closing a file
+Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
-descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means,
+a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
-such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file
+means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
-descriptor, but when it goes away, the operating system will silently drop
+file descriptor, but when it goes away, the operating system will silently
-this interest. If another file descriptor with the same number then is
+drop this interest. If another file descriptor with the same number then
-registered with libev, there is no efficient way to see that this is, in
+is registered with libev, there is no efficient way to see that this is,
-fact, a different file descriptor.
+in fact, a different file descriptor.
 .PP
 To avoid having to explicitly tell libev about such cases, libev follows
 the following policy:  Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
 will assume that this is potentially a new file descriptor, otherwise
 it is assumed that the file descriptor stays the same. That means that
 reuse the same code path.
 .PP
 \fIThe special problem of fork\fR
 .IX Subsection "The special problem of fork"
 .PP
-Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit
+Some backends (epoll, kqueue, probably linuxaio) do not support \f(CW\*(C`fork ()\*(C'\fR
-useless behaviour. Libev fully supports fork, but needs to be told about
+at all or exhibit useless behaviour. Libev fully supports fork, but needs
-it in the child if you want to continue to use it in the child.
+to be told about it in the child if you want to continue to use it in the
+child.
 .PP
 To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
 ()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
 \&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
 .PP
 when writing to a pipe whose other end has been closed, your program gets
 sent a \s-1SIGPIPE,\s0 which, by default, aborts your program. For most programs
 this is sensible behaviour, for daemons, this is usually undesirable.
 .PP
 So when you encounter spurious, unexplained daemon exits, make sure you
-ignore \s-1SIGPIPE \s0(and maybe make sure you log the exit status of your daemon
+ignore \s-1SIGPIPE\s0 (and maybe make sure you log the exit status of your daemon
 somewhere, as that would have given you a big clue).
 .PP
-\fIThe special problem of \fIaccept()\fIing when you can't\fR
+\fIThe special problem of \f(BIaccept()\fIing when you can't\fR
 .IX Subsection "The special problem of accept()ing when you can't"
 .PP
-Many implementations of the \s-1POSIX \s0\f(CW\*(C`accept\*(C'\fR function (for example,
+Many implementations of the \s-1POSIX\s0 \f(CW\*(C`accept\*(C'\fR function (for example,
 found in post\-2004 Linux) have the peculiar behaviour of not removing a
 connection from the pending queue in all error cases.
 .PP
 For example, larger servers often run out of file descriptors (because
 of resource limits), causing \f(CW\*(C`accept\*(C'\fR to fail with \f(CW\*(C`ENFILE\*(C'\fR but not
 .IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
 .PD 0
 .IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
 .IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
 .PD
-Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR
+Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
-is \f(CW0.\fR, then it will automatically be stopped once the timeout is
+negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
-reached. If it is positive, then the timer will automatically be
+automatically be stopped once the timeout is reached. If it is positive,
-configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again,
+then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
-until stopped manually.
+seconds later, again, and again, until stopped manually.
 .Sp
 The timer itself will do a best-effort at avoiding drift, that is, if
 you configure a timer to trigger every 10 seconds, then it will normally
 trigger at exactly 10 second intervals. If, however, your program cannot
 keep up with the timer (because it takes longer than those 10 seconds to
 \&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
 it, as it uses a relative timeout).
 .PP
 \&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
 timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
-other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as
+other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
-those cannot react to time jumps.
+watchers, as those cannot react to time jumps.
 .PP
 As with timers, the callback is guaranteed to be invoked only when the
 point in time where it is supposed to trigger has passed. If multiple
 timers become ready during the same loop iteration then the ones with
 earlier time-out values are invoked before ones with later time-out values
 In this mode the values for \f(CW\*(C`interval\*(C'\fR and \f(CW\*(C`offset\*(C'\fR are both being
 ignored. Instead, each time the periodic watcher gets scheduled, the
 reschedule callback will be called with the watcher as first, and the
 current time as second argument.
 .Sp
-\&\s-1NOTE: \s0\fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
+\&\s-1NOTE:\s0 \fIThis callback \s-1MUST NOT\s0 stop or destroy any periodic watcher, ever,
 or make \s-1ANY\s0 other event loop modifications whatsoever, unless explicitly
 allowed by documentation here\fR.
 .Sp
 If you need to stop it, return \f(CW\*(C`now + 1e30\*(C'\fR (or so, fudge fudge) and stop
 it afterwards (e.g. by starting an \f(CW\*(C`ev_prepare\*(C'\fR watcher, which is the
 It must return the next time to trigger, based on the passed time value
 (that is, the lowest time value larger than to the second argument). It
 will usually be called just before the callback will be triggered, but
 might be called at other times, too.
 .Sp
-\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or
+\&\s-1NOTE:\s0 \fIThis callback must always return a time that is higher than or
 equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
 .Sp
 This can be used to create very complex timers, such as a timer that
-triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the
+triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
-next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How
+the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
-you do this is, again, up to you (but it is not trivial, which is the main
+this. Here is a (completely untested, no error checking) example on how to
-reason I omitted it as an example).
+do this:
+.Sp
+.Vb 1
+\&   #include <time.h>
+\&
+\&   static ev_tstamp
+\&   my_rescheduler (ev_periodic *w, ev_tstamp now)
+\&   {
+\&     time_t tnow = (time_t)now;
+\&     struct tm tm;
+\&     localtime_r (&tnow, &tm);
+\&
+\&     tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
+\&     ++tm.tm_mday; // midnight next day
+\&
+\&     return mktime (&tm);
+\&   }
+.Ve
+.Sp
+Note: this code might run into trouble on days that have more then two
+midnights (beginning and end).
 .RE
 .RS 4
 .RE
 .IP "ev_periodic_again (loop, ev_periodic *)" 4
 .IX Item "ev_periodic_again (loop, ev_periodic *)"
 The simplest way to ensure that the signal mask is reset in the child is
 to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will
 catch fork calls done by libraries (such as the libc) as well.
 .PP
 In current versions of libev, the signal will not be blocked indefinitely
-unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API \s0(\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
+unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces
 the window of opportunity for problems, it will not go away, as libev
 \&\fIhas\fR to modify the signal mask, at least temporarily.
 .PP
 So I can't stress this enough: \fIIf you do not reset your signal mask when
 you expect it to be empty, you have a race condition in your code\fR. This
 is a time window between the event loop checking and resetting the async
 notification, and the callback being invoked.
 .SH "OTHER FUNCTIONS"
 .IX Header "OTHER FUNCTIONS"
 There are some other functions of possible interest. Described. Here. Now.
-.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
+.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
-.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
+.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
 This function combines a simple timer and an I/O watcher, calls your
 callback on whichever event happens first and automatically stops both
 watchers. This is useful if you want to wait for a single event on an fd
 or timeout without having to allocate/configure/start/stop/free one or
 more watchers yourself.
 The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
 libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
 will work fine.
 .PP
 Proper exception specifications might have to be added to callbacks passed
-to libev: exceptions may be thrown only from watcher callbacks, all
+to libev: exceptions may be thrown only from watcher callbacks, all other
-other callbacks (allocator, syserr, loop acquire/release and periodic
+callbacks (allocator, syserr, loop acquire/release and periodic reschedule
-reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw
+callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
-()\*(C'\fR specification. If you have code that needs to be compiled as both C
+specification. If you have code that needs to be compiled as both C and
-and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
+\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
 .PP
 .Vb 6
 \&   static void
-\&   fatal_error (const char *msg) EV_THROW
+\&   fatal_error (const char *msg) EV_NOEXCEPT
 \&   {
 \&     perror (msg);
 \&     abort ();
 \&   }
 \&
 \&   #include "ev.c"
 .Ve
 .PP
 This will automatically include \fIev.h\fR, too, and should be done in a
 single C source file only to provide the function implementations. To use
-it, do the same for \fIev.h\fR in all files wishing to use this \s-1API \s0(best
+it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
 done by writing a wrapper around \fIev.h\fR that you can include instead and
 where you can put other configuration options):
 .PP
 .Vb 2
 \&   #define EV_STANDALONE 1
 \&   ev_win32.c      required on win32 platforms only
 \&
 \&   ev_select.c     only when select backend is enabled
 \&   ev_poll.c       only when poll backend is enabled
 \&   ev_epoll.c      only when the epoll backend is enabled
+\&   ev_linuxaio.c   only when the linux aio backend is enabled
 \&   ev_kqueue.c     only when the kqueue backend is enabled
 \&   ev_port.c       only when the solaris port backend is enabled
 .Ve
 .PP
 \&\fIev.c\fR includes the backend files directly when enabled, so you only need
 values when compiling libev vs. including \fIev.h\fR, so it is permissible
 to redefine them before including \fIev.h\fR without breaking compatibility
 to a compiled library. All other symbols change the \s-1ABI,\s0 which means all
 users of libev and the libev code itself must be compiled with compatible
 settings.
-.IP "\s-1EV_COMPAT3 \s0(h)" 4
+.IP "\s-1EV_COMPAT3\s0 (h)" 4
 .IX Item "EV_COMPAT3 (h)"
 Backwards compatibility is a major concern for libev. This is why this
 release of libev comes with wrappers for the functions and symbols that
 have been renamed between libev version 3 and 4.
 .Sp
 typedef in that case.
 .Sp
 In some future version, the default for \f(CW\*(C`EV_COMPAT3\*(C'\fR will become \f(CW0\fR,
 and in some even more future version the compatibility code will be
 removed completely.
-.IP "\s-1EV_STANDALONE \s0(h)" 4
+.IP "\s-1EV_STANDALONE\s0 (h)" 4
 .IX Item "EV_STANDALONE (h)"
 Must always be \f(CW1\fR if you do not use autoconf configuration, which
 keeps libev from including \fIconfig.h\fR, and it also defines dummy
 implementations for some libevent functions (such as logging, which is not
 supported). It will also not define any of the structs usually found in
 If defined to be \f(CW1\fR, libev will compile in support for the Linux
 \&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
 otherwise another method will be used as fallback. This is the preferred
 backend for GNU/Linux systems. If undefined, it will be enabled if the
 headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
+.IP "\s-1EV_USE_LINUXAIO\s0" 4
+.IX Item "EV_USE_LINUXAIO"
+If defined to be \f(CW1\fR, libev will compile in support for the Linux
+aio backend. Due to it's currenbt limitations it has to be requested
+explicitly.  If undefined, it will be enabled on linux, otherwise
+disabled.
 .IP "\s-1EV_USE_KQUEUE\s0" 4
 .IX Item "EV_USE_KQUEUE"
 If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
 \&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
 otherwise another method will be used as fallback. This is the preferred
 handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
 watchers.
 .Sp
 In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
 (from \fIsignal.h\fR), which is usually good enough on most platforms.
-.IP "\s-1EV_H \s0(h)" 4
+.IP "\s-1EV_H\s0 (h)" 4
 .IX Item "EV_H (h)"
 The name of the \fIev.h\fR header file used to include it. The default if
 undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
 used to virtually rename the \fIev.h\fR header file in case of conflicts.
-.IP "\s-1EV_CONFIG_H \s0(h)" 4
+.IP "\s-1EV_CONFIG_H\s0 (h)" 4
 .IX Item "EV_CONFIG_H (h)"
 If \f(CW\*(C`EV_STANDALONE\*(C'\fR isn't \f(CW1\fR, this variable can be used to override
 \&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
 \&\f(CW\*(C`EV_H\*(C'\fR, above.
-.IP "\s-1EV_EVENT_H \s0(h)" 4
+.IP "\s-1EV_EVENT_H\s0 (h)" 4
 .IX Item "EV_EVENT_H (h)"
 Similarly to \f(CW\*(C`EV_H\*(C'\fR, this macro can be used to override \fIevent.c\fR's idea
 of how the \fIevent.h\fR header can be found, the default is \f(CW"event.h"\fR.
-.IP "\s-1EV_PROTOTYPES \s0(h)" 4
+.IP "\s-1EV_PROTOTYPES\s0 (h)" 4
 .IX Item "EV_PROTOTYPES (h)"
 If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
 prototypes, but still define all the structs and other symbols. This is
 occasionally useful if you want to provide your own wrapper functions
 around libev functions.
 .Vb 3
 \&   #define EV_COMMON                       \e
 \&     SV *self; /* contains this struct */  \e
 \&     SV *cb_sv, *fh /* note no trailing ";" */
 .Ve
-.IP "\s-1EV_CB_DECLARE \s0(type)" 4
+.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
 .IX Item "EV_CB_DECLARE (type)"
 .PD 0
-.IP "\s-1EV_CB_INVOKE \s0(watcher, revents)" 4
+.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
 .IX Item "EV_CB_INVOKE (watcher, revents)"
 .IP "ev_set_cb (ev, cb)" 4
 .IX Item "ev_set_cb (ev, cb)"
 .PD
 Can be used to change the callback member declaration in each watcher,
 their default definitions. One possible use for overriding these is to
 avoid the \f(CW\*(C`struct ev_loop *\*(C'\fR as first argument in all cases, or to use
 method calls instead of plain function calls in \*(C+.
 .SS "\s-1EXPORTED API SYMBOLS\s0"
 .IX Subsection "EXPORTED API SYMBOLS"
-If you need to re-export the \s-1API \s0(e.g. via a \s-1DLL\s0) and you need a list of
+If you need to re-export the \s-1API\s0 (e.g. via a \s-1DLL\s0) and you need a list of
 exported symbols, you can use the provided \fISymbol.*\fR files which list
 all public symbols, one per line:
 .PP
 .Vb 2
 \&   Symbols.ev      for libev proper
 .PP
 \fI\f(CI\*(C`select\*(C'\fI is buggy\fR
 .IX Subsection "select is buggy"
 .PP
 All that's left is \f(CW\*(C`select\*(C'\fR, and of course Apple found a way to fuck this
-one up as well: On \s-1OS/X, \s0\f(CW\*(C`select\*(C'\fR actively limits the number of file
+one up as well: On \s-1OS/X,\s0 \f(CW\*(C`select\*(C'\fR actively limits the number of file
 descriptors you can pass in to 1024 \- your program suddenly crashes when
 you use more.
 .PP
 There is an undocumented \*(L"workaround\*(R" for this \- defining
 \&\f(CW\*(C`_DARWIN_UNLIMITED_SELECT\*(C'\fR, which libev tries to use, so select \fIshould\fR

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.3 (file contents): Revision 1.108 by root, Sat Jul 28 04:15:15 2018 UTC vs. Revision 1.112 by root, Sun Jun 23 23:27:34 2019 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.108 by root, Sat Jul 28 04:15:15 2018 UTC vs.
Revision 1.112 by root, Sun Jun 23 23:27:34 2019 UTC