ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

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

105details of the event, and then hand it over to libev by I<starting> the 105details of the event, and then hand it over to libev by I<starting> the
106watcher. 106watcher.
107 107
108=head2 FEATURES 108=head2 FEATURES
109 109
110Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 110Libev supports C<select>, C<poll>, the Linux-specific aio and C<epoll>
111BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 111interfaces, the BSD-specific C<kqueue> and the Solaris-specific event port
112for file descriptor events (C<ev_io>), the Linux C<inotify> interface 112mechanisms for file descriptor events (C<ev_io>), the Linux C<inotify>
113(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner 113interface (for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
114inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative 114inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
115timers (C<ev_timer>), absolute timers with customised rescheduling 115timers (C<ev_timer>), absolute timers with customised rescheduling
116(C<ev_periodic>), synchronous signals (C<ev_signal>), process status 116(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
117change events (C<ev_child>), and event watchers dealing with the event 117change events (C<ev_child>), and event watchers dealing with the event
118loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and 118loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
567All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or 567All this means that, in practice, C<EVBACKEND_SELECT> can be as fast or
568faster than epoll for maybe up to a hundred file descriptors, depending on 568faster than epoll for maybe up to a hundred file descriptors, depending on
569the usage. So sad. 569the usage. So sad.
570 570
571While nominally embeddable in other event loops, this feature is broken in 571While nominally embeddable in other event loops, this feature is broken in
572all kernel versions tested so far. 572a lot of kernel revisions, but probably(!) works in current versions.
573
574This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
575C<EVBACKEND_POLL>.
576
577=item C<EVBACKEND_LINUXAIO> (value 64, Linux)
578
579Use the linux-specific linux aio (I<not> C<< aio(7) >> but C<<
580io_submit(2) >>) event interface available in post-4.18 kernels.
581
582If this backend works for you (as of this writing, it was very
583experimental), it is the best event interface available on linux and might
584be well worth enabling it - if it isn't available in your kernel this will
585be detected and this backend will be skipped.
586
587This backend can batch oneshot requests and supports a user-space ring
588buffer to receive events. It also doesn't suffer from most of the design
589problems of epoll (such as not being able to remove event sources from
590the epoll set), and generally sounds too good to be true. Because, this
591being the linux kernel, of course it suffers from a whole new set of
592limitations.
593
594For one, it is not easily embeddable (but probably could be done using
595an event fd at some extra overhead). It also is subject to a system wide
596limit that can be configured in F</proc/sys/fs/aio-max-nr> - each loop
597currently requires C<61> of this number. If no aio requests are left, this
598backend will be skipped during initialisation.
599
600Most problematic in practise, however, is that not all file descriptors
601work with it. For example, in linux 5.1, tcp sockets, pipes, event fds,
602files, F</dev/null> and a few others are supported, but ttys do not work
603properly (a known bug that the kernel developers don't care about, see
604L<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
605(yet?) a generic event polling interface.
606
607To work around this latter problem, the current version of libev uses
608epoll as a fallback for file deescriptor types that do not work. Epoll
609is used in, kind of, slow mode that hopefully avoids most of its design
610problems and requires 1-3 extra syscalls per active fd every iteration.
573 611
574This backend maps C<EV_READ> and C<EV_WRITE> in the same way as 612This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
575C<EVBACKEND_POLL>. 613C<EVBACKEND_POLL>.
576 614
577=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 615=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
677 715
678Example: Use whatever libev has to offer, but make sure that kqueue is 716Example: Use whatever libev has to offer, but make sure that kqueue is
679used if available. 717used if available.
680 718
681 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 719 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
720
721Example: Similarly, on linux, you mgiht want to take advantage of the
722linux aio backend if possible, but fall back to something else if that
723isn't available.
724
725 struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
682 726
683=item ev_loop_destroy (loop) 727=item ev_loop_destroy (loop)
684 728
685Destroys an event loop object (frees all memory and kernel state 729Destroys an event loop object (frees all memory and kernel state
686etc.). None of the active event watchers will be stopped in the normal 730etc.). None of the active event watchers will be stopped in the normal
1630 1674
1631But really, best use non-blocking mode. 1675But really, best use non-blocking mode.
1632 1676
1633=head3 The special problem of disappearing file descriptors 1677=head3 The special problem of disappearing file descriptors
1634 1678
1635Some backends (e.g. kqueue, epoll) need to be told about closing a file 1679Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1636descriptor (either due to calling C<close> explicitly or any other means, 1680a file descriptor (either due to calling C<close> explicitly or any other
1637such as C<dup2>). The reason is that you register interest in some file 1681means, such as C<dup2>). The reason is that you register interest in some
1638descriptor, but when it goes away, the operating system will silently drop 1682file descriptor, but when it goes away, the operating system will silently
1639this interest. If another file descriptor with the same number then is 1683drop this interest. If another file descriptor with the same number then
1640registered with libev, there is no efficient way to see that this is, in 1684is registered with libev, there is no efficient way to see that this is,
1641fact, a different file descriptor. 1685in fact, a different file descriptor.
1642 1686
1643To avoid having to explicitly tell libev about such cases, libev follows 1687To avoid having to explicitly tell libev about such cases, libev follows
1644the following policy: Each time C<ev_io_set> is being called, libev 1688the following policy: Each time C<ev_io_set> is being called, libev
1645will assume that this is potentially a new file descriptor, otherwise 1689will assume that this is potentially a new file descriptor, otherwise
1646it is assumed that the file descriptor stays the same. That means that 1690it is assumed that the file descriptor stays the same. That means that
1695when you rarely read from a file instead of from a socket, and want to 1739when you rarely read from a file instead of from a socket, and want to
1696reuse the same code path. 1740reuse the same code path.
1697 1741
1698=head3 The special problem of fork 1742=head3 The special problem of fork
1699 1743
1700Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit 1744Some backends (epoll, kqueue, probably linuxaio) do not support C<fork ()>
1701useless behaviour. Libev fully supports fork, but needs to be told about 1745at all or exhibit useless behaviour. Libev fully supports fork, but needs
1702it in the child if you want to continue to use it in the child. 1746to be told about it in the child if you want to continue to use it in the
1747child.
1703 1748
1704To support fork in your child processes, you have to call C<ev_loop_fork 1749To support fork in your child processes, you have to call C<ev_loop_fork
1705()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to 1750()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
1706C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1751C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1707 1752
4428 ev_win32.c required on win32 platforms only 4473 ev_win32.c required on win32 platforms only
4429 4474
4430 ev_select.c only when select backend is enabled 4475 ev_select.c only when select backend is enabled
4431 ev_poll.c only when poll backend is enabled 4476 ev_poll.c only when poll backend is enabled
4432 ev_epoll.c only when the epoll backend is enabled 4477 ev_epoll.c only when the epoll backend is enabled
4478 ev_linuxaio.c only when the linux aio backend is enabled
4433 ev_kqueue.c only when the kqueue backend is enabled 4479 ev_kqueue.c only when the kqueue backend is enabled
4434 ev_port.c only when the solaris port backend is enabled 4480 ev_port.c only when the solaris port backend is enabled
4435 4481
4436F<ev.c> includes the backend files directly when enabled, so you only need 4482F<ev.c> includes the backend files directly when enabled, so you only need
4437to compile this single file. 4483to compile this single file.
4627If defined to be C<1>, libev will compile in support for the Linux 4673If defined to be C<1>, libev will compile in support for the Linux
4628C<epoll>(7) backend. Its availability will be detected at runtime, 4674C<epoll>(7) backend. Its availability will be detected at runtime,
4629otherwise another method will be used as fallback. This is the preferred 4675otherwise another method will be used as fallback. This is the preferred
4630backend for GNU/Linux systems. If undefined, it will be enabled if the 4676backend for GNU/Linux systems. If undefined, it will be enabled if the
4631headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4677headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4678
4679=item EV_USE_LINUXAIO
4680
4681If defined to be C<1>, libev will compile in support for the Linux
4682aio backend. Due to it's currenbt limitations it has to be requested
4683explicitly. If undefined, it will be enabled on linux, otherwise
4684disabled.
4632 4685
4633=item EV_USE_KQUEUE 4686=item EV_USE_KQUEUE
4634 4687
4635If defined to be C<1>, libev will compile in support for the BSD style 4688If defined to be C<1>, libev will compile in support for the BSD style
4636C<kqueue>(2) backend. Its actual availability will be detected at runtime, 4689C<kqueue>(2) backend. Its actual availability will be detected at runtime,

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines