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

Comparing libev/ev.pod (file contents):
Revision 1.446 by root, Mon Mar 18 19:28:15 2019 UTC vs.
Revision 1.451 by root, Mon Jun 24 00:19:26 2019 UTC

 details of the event, and then hand it over to libev by I<starting> the
 watcher.
 =head2 FEATURES
-Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
+Libev supports C<select>, C<poll>, the Linux-specific aio and C<epoll>
-BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
+interfaces, the BSD-specific C<kqueue> and the Solaris-specific event port
-for file descriptor events (C<ev_io>), the Linux C<inotify> interface
+mechanisms for file descriptor events (C<ev_io>), the Linux C<inotify>
-(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
+interface (for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
 inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
 timers (C<ev_timer>), absolute timers with customised rescheduling
 (C<ev_periodic>), synchronous signals (C<ev_signal>), process status
 change events (C<ev_child>), and event watchers dealing with the event
 loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
 All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
 faster than epoll for maybe up to a hundred file descriptors, depending on
 the usage. So sad.
 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.
+This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
+C<EVBACKEND_POLL>.
+=item C<EVBACKEND_LINUXAIO>   (value 64, Linux)
+Use the linux-specific linux aio (I<not> C<< aio(7) >> but C<<
+io_submit(2) >>) event interface available in post-4.18 kernels.
+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.
+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.
+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 F</proc/sys/fs/aio-max-nr> - each loop
+currently requires C<61> of this number. If no aio requests are left, this
+backend will be skipped during initialisation.
+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, F</dev/null> and a few others are supported, but ttys do not work
+properly (a known bug that the kernel developers don't care about, see
+L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
+(yet?) a generic event polling interface.
+Overall, it seems the linux developers just don't want it to have a
+generic event handling mechanism other than C<select> or C<poll>.
+To work around the fd type 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.
 This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
 C<EVBACKEND_POLL>.
 =item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
 Example: Use whatever libev has to offer, but make sure that kqueue is
 used if available.
    struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
+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.
+   struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
 =item ev_loop_destroy (loop)
 Destroys an event loop object (frees all memory and kernel state
 etc.). None of the active event watchers will be stopped in the normal
 But really, best use non-blocking mode.
 =head3 The special problem of disappearing file descriptors
-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 C<close> explicitly or any other means,
+a file descriptor (either due to calling C<close> explicitly or any other
-such as C<dup2>). The reason is that you register interest in some file
+means, such as C<dup2>). 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.
 To avoid having to explicitly tell libev about such cases, libev follows
 the following policy:  Each time C<ev_io_set> 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
 when you rarely read from a file instead of from a socket, and want to
 reuse the same code path.
 =head3 The special problem of fork
-Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
+Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()>
-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.
 To support fork in your child processes, you have to call C<ev_loop_fork
 ()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
 C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
    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
 F<ev.c> includes the backend files directly when enabled, so you only need
 to compile this single file.
 If defined to be C<1>, libev will compile in support for the Linux
 C<epoll>(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.
+=item EV_USE_LINUXAIO
+If defined to be C<1>, 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.
 =item EV_USE_KQUEUE
 If defined to be C<1>, libev will compile in support for the BSD style
 C<kqueue>(2) backend. Its actual availability will be detected at runtime,

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.446 by root, Mon Mar 18 19:28:15 2019 UTC vs. Revision 1.451 by root, Mon Jun 24 00:19:26 2019 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.446 by root, Mon Mar 18 19:28:15 2019 UTC vs.
Revision 1.451 by root, Mon Jun 24 00:19:26 2019 UTC