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

Comparing libev/ev.3 (file contents):
Revision 1.110 by root, Thu Jun 20 22:44:59 2019 UTC vs.
Revision 1.114 by root, Tue Jun 25 06:36:59 2019 UTC

… …
131.\} 131.\}
132.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
133.\" ======================================================================== 133.\" ========================================================================
134.\" 134.\"
135.IX Title "LIBEV 3" 135.IX Title "LIBEV 3"
136.TH LIBEV 3 "2019-06-20" "libev-4.25" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-06-25" "libev-4.25" "libev - high performance full featured event loop"
137.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
139.if n .ad l 139.if n .ad l
140.nh 140.nh
141.SH "NAME" 141.SH "NAME"
… …
240watchers\fR, which are relatively small C structures you initialise with the 240watchers\fR, which are relatively small C structures you initialise with the
241details of the event, and then hand it over to libev by \fIstarting\fR the 241details of the event, and then hand it over to libev by \fIstarting\fR the
242watcher. 242watcher.
243.SS "\s-1FEATURES\s0" 243.SS "\s-1FEATURES\s0"
244.IX Subsection "FEATURES" 244.IX Subsection "FEATURES"
245Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the 245Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific aio and \f(CW\*(C`epoll\*(C'\fR
246BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms 246interfaces, the BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port
247for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface 247mechanisms for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR
248(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner 248interface (for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner
249inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative 249inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative
250timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling 250timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling
251(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status 251(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status
252change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event 252change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event
253loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and 253loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
… …
638This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 638This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and
639\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. 639\&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR.
640.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 640.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
641.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 641.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
642.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 642.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
643Use the linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 643Use the Linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
644kernels). 644kernels).
645.Sp 645.Sp
646For few fds, this backend is a bit little slower than poll and select, but 646For few fds, this backend is a bit little slower than poll and select, but
647it scales phenomenally better. While poll and select usually scale like 647it scales phenomenally better. While poll and select usually scale like
648O(total_fds) where total_fds is the total number of fds (or the highest 648O(total_fds) where total_fds is the total number of fds (or the highest
… …
694All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or 694All this means that, in practice, \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR can be as fast or
695faster than epoll for maybe up to a hundred file descriptors, depending on 695faster than epoll for maybe up to a hundred file descriptors, depending on
696the usage. So sad. 696the usage. So sad.
697.Sp 697.Sp
698While nominally embeddable in other event loops, this feature is broken in 698While nominally embeddable in other event loops, this feature is broken in
699all kernel versions tested so far. 699a lot of kernel revisions, but probably(!) works in current versions.
700.Sp
701This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
702\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
703.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
704.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
705.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
706Use the Linux-specific Linux \s-1AIO\s0 (\fInot\fR \f(CWaio(7)\fR but \f(CWio_submit(2)\fR) event interface available in post\-4.18 kernels (but libev
707only tries to use it in 4.19+).
708.Sp
709This is another Linux train wreck of an event interface.
710.Sp
711If this backend works for you (as of this writing, it was very
712experimental), it is the best event interface available on Linux and might
713be well worth enabling it \- if it isn't available in your kernel this will
714be detected and this backend will be skipped.
715.Sp
716This backend can batch oneshot requests and supports a user-space ring
717buffer to receive events. It also doesn't suffer from most of the design
718problems of epoll (such as not being able to remove event sources from
719the epoll set), and generally sounds too good to be true. Because, this
720being the Linux kernel, of course it suffers from a whole new set of
721limitations, forcing you to fall back to epoll, inheriting all its design
722issues.
723.Sp
724For one, it is not easily embeddable (but probably could be done using
725an event fd at some extra overhead). It also is subject to a system wide
726limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR. If no \s-1AIO\s0
727requests are left, this backend will be skipped during initialisation, and
728will switch to epoll when the loop is active.
729.Sp
730Most problematic in practice, however, is that not all file descriptors
731work with it. For example, in Linux 5.1, \s-1TCP\s0 sockets, pipes, event fds,
732files, \fI/dev/null\fR and many others are supported, but ttys do not work
733properly (a known bug that the kernel developers don't care about, see
734<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
735(yet?) a generic event polling interface.
736.Sp
737Overall, it seems the Linux developers just don't want it to have a
738generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
739.Sp
740To work around all these problem, the current version of libev uses its
741epoll backend as a fallback for file descriptor types that do not work. Or
742falls back completely to epoll if the kernel acts up.
700.Sp 743.Sp
701This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 744This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
702\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 745\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
703.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 746.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
704.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 747.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
705.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 748.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
706Kqueue deserves special mention, as at the time of this writing, it 749Kqueue deserves special mention, as at the time this backend was
707was broken on all BSDs except NetBSD (usually it doesn't work reliably 750implemented, it was broken on all BSDs except NetBSD (usually it doesn't
708with anything but sockets and pipes, except on Darwin, where of course 751work reliably with anything but sockets and pipes, except on Darwin,
709it's completely useless). Unlike epoll, however, whose brokenness 752where of course it's completely useless). Unlike epoll, however, whose
710is by design, these kqueue bugs can (and eventually will) be fixed 753brokenness is by design, these kqueue bugs can be (and mostly have been)
711without \s-1API\s0 changes to existing programs. For this reason it's not being 754fixed without \s-1API\s0 changes to existing programs. For this reason it's not
712\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using 755being \*(L"auto-detected\*(R" on all platforms unless you explicitly specify it
713\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) 756in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
714system like NetBSD. 757known-to-be-good (\-enough) system like NetBSD.
715.Sp 758.Sp
716You still can embed kqueue into a normal poll or select backend and use it 759You still can embed kqueue into a normal poll or select backend and use it
717only for sockets (after having made sure that sockets work with kqueue on 760only for sockets (after having made sure that sockets work with kqueue on
718the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 761the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
719.Sp 762.Sp
720It scales in the same way as the epoll backend, but the interface to the 763It scales in the same way as the epoll backend, but the interface to the
721kernel is more efficient (which says nothing about its actual speed, of 764kernel is more efficient (which says nothing about its actual speed, of
722course). While stopping, setting and starting an I/O watcher does never 765course). While stopping, setting and starting an I/O watcher does never
723cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 766cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
724two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you 767two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
725might have to leak fd's on fork, but it's more sane than epoll) and it 768might have to leak fds on fork, but it's more sane than epoll) and it
726drops fds silently in similarly hard-to-detect cases. 769drops fds silently in similarly hard-to-detect cases.
727.Sp 770.Sp
728This backend usually performs well under most conditions. 771This backend usually performs well under most conditions.
729.Sp 772.Sp
730While nominally embeddable in other event loops, this doesn't work 773While nominally embeddable in other event loops, this doesn't work
… …
807Example: Use whatever libev has to offer, but make sure that kqueue is 850Example: Use whatever libev has to offer, but make sure that kqueue is
808used if available. 851used if available.
809.Sp 852.Sp
810.Vb 1 853.Vb 1
811\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 854\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
855.Ve
856.Sp
857Example: Similarly, on linux, you mgiht want to take advantage of the
858linux aio backend if possible, but fall back to something else if that
859isn't available.
860.Sp
861.Vb 1
862\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
812.Ve 863.Ve
813.RE 864.RE
814.IP "ev_loop_destroy (loop)" 4 865.IP "ev_loop_destroy (loop)" 4
815.IX Item "ev_loop_destroy (loop)" 866.IX Item "ev_loop_destroy (loop)"
816Destroys an event loop object (frees all memory and kernel state 867Destroys an event loop object (frees all memory and kernel state
… …
1748But really, best use non-blocking mode. 1799But really, best use non-blocking mode.
1749.PP 1800.PP
1750\fIThe special problem of disappearing file descriptors\fR 1801\fIThe special problem of disappearing file descriptors\fR
1751.IX Subsection "The special problem of disappearing file descriptors" 1802.IX Subsection "The special problem of disappearing file descriptors"
1752.PP 1803.PP
1753Some backends (e.g. kqueue, epoll) need to be told about closing a file 1804Some backends (e.g. kqueue, epoll, linuxaio) need to be told about closing
1754descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other means, 1805a file descriptor (either due to calling \f(CW\*(C`close\*(C'\fR explicitly or any other
1755such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some file 1806means, such as \f(CW\*(C`dup2\*(C'\fR). The reason is that you register interest in some
1756descriptor, but when it goes away, the operating system will silently drop 1807file descriptor, but when it goes away, the operating system will silently
1757this interest. If another file descriptor with the same number then is 1808drop this interest. If another file descriptor with the same number then
1758registered with libev, there is no efficient way to see that this is, in 1809is registered with libev, there is no efficient way to see that this is,
1759fact, a different file descriptor. 1810in fact, a different file descriptor.
1760.PP 1811.PP
1761To avoid having to explicitly tell libev about such cases, libev follows 1812To avoid having to explicitly tell libev about such cases, libev follows
1762the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev 1813the following policy: Each time \f(CW\*(C`ev_io_set\*(C'\fR is being called, libev
1763will assume that this is potentially a new file descriptor, otherwise 1814will assume that this is potentially a new file descriptor, otherwise
1764it is assumed that the file descriptor stays the same. That means that 1815it is assumed that the file descriptor stays the same. That means that
… …
1816reuse the same code path. 1867reuse the same code path.
1817.PP 1868.PP
1818\fIThe special problem of fork\fR 1869\fIThe special problem of fork\fR
1819.IX Subsection "The special problem of fork" 1870.IX Subsection "The special problem of fork"
1820.PP 1871.PP
1821Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1872Some backends (epoll, kqueue, probably linuxaio) do not support \f(CW\*(C`fork ()\*(C'\fR
1822useless behaviour. Libev fully supports fork, but needs to be told about 1873at all or exhibit useless behaviour. Libev fully supports fork, but needs
1823it in the child if you want to continue to use it in the child. 1874to be told about it in the child if you want to continue to use it in the
1875child.
1824.PP 1876.PP
1825To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1877To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
1826()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to 1878()\*(C'\fR after a fork in the child, enable \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR, or resort to
1827\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 1879\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1828.PP 1880.PP
… …
4567\& ev_win32.c required on win32 platforms only 4619\& ev_win32.c required on win32 platforms only
4568\& 4620\&
4569\& ev_select.c only when select backend is enabled 4621\& ev_select.c only when select backend is enabled
4570\& ev_poll.c only when poll backend is enabled 4622\& ev_poll.c only when poll backend is enabled
4571\& ev_epoll.c only when the epoll backend is enabled 4623\& ev_epoll.c only when the epoll backend is enabled
4624\& ev_linuxaio.c only when the linux aio backend is enabled
4572\& ev_kqueue.c only when the kqueue backend is enabled 4625\& ev_kqueue.c only when the kqueue backend is enabled
4573\& ev_port.c only when the solaris port backend is enabled 4626\& ev_port.c only when the solaris port backend is enabled
4574.Ve 4627.Ve
4575.PP 4628.PP
4576\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4629\&\fIev.c\fR includes the backend files directly when enabled, so you only need
… …
4757If defined to be \f(CW1\fR, libev will compile in support for the Linux 4810If defined to be \f(CW1\fR, libev will compile in support for the Linux
4758\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime, 4811\&\f(CW\*(C`epoll\*(C'\fR(7) backend. Its availability will be detected at runtime,
4759otherwise another method will be used as fallback. This is the preferred 4812otherwise another method will be used as fallback. This is the preferred
4760backend for GNU/Linux systems. If undefined, it will be enabled if the 4813backend for GNU/Linux systems. If undefined, it will be enabled if the
4761headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4814headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4815.IP "\s-1EV_USE_LINUXAIO\s0" 4
4816.IX Item "EV_USE_LINUXAIO"
4817If defined to be \f(CW1\fR, libev will compile in support for the Linux
4818aio backend. Due to it's currenbt limitations it has to be requested
4819explicitly. If undefined, it will be enabled on linux, otherwise
4820disabled.
4762.IP "\s-1EV_USE_KQUEUE\s0" 4 4821.IP "\s-1EV_USE_KQUEUE\s0" 4
4763.IX Item "EV_USE_KQUEUE" 4822.IX Item "EV_USE_KQUEUE"
4764If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4823If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4765\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4824\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4766otherwise another method will be used as fallback. This is the preferred 4825otherwise another method will be used as fallback. This is the preferred

Diff Legend

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