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.112 by root, Sun Jun 23 23:27:34 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-23" "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
… …
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 aio (\fInot\fR \f(CWaio(7)\fR but \f(CWio_submit(2)\fR) event interface available in post\-4.18 kernels.
707.Sp
708If this backend works for you (as of this writing, it was very
709experimental), it is the best event interface available on linux and might
710be well worth enabling it \- if it isn't available in your kernel this will
711be detected and this backend will be skipped.
712.Sp
713This backend can batch oneshot requests and supports a user-space ring
714buffer to receive events. It also doesn't suffer from most of the design
715problems of epoll (such as not being able to remove event sources from
716the epoll set), and generally sounds too good to be true. Because, this
717being the linux kernel, of course it suffers from a whole new set of
718limitations.
719.Sp
720For one, it is not easily embeddable (but probably could be done using
721an event fd at some extra overhead). It also is subject to a system wide
722limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR \- each loop
723currently requires \f(CW61\fR of this number. If no aio requests are left, this
724backend will be skipped during initialisation.
725.Sp
726Most problematic in practise, however, is that not all file descriptors
727work with it. For example, in linux 5.1, tcp sockets, pipes, event fds,
728files, \fI/dev/null\fR and a few others are supported, but ttys do not work
729(probably because of a bug), so this is not (yet?) a generic event polling
730interface.
731.Sp
732To work around this latter problem, the current version of libev uses
733epoll as a fallback for file deescriptor types that do not work. Epoll
734is used in, kind of, slow mode that hopefully avoids most of its design
735problems and requires 1\-3 extra syscalls per active fd every iteration.
700.Sp 736.Sp
701This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 737This 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. 738\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
703.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 739.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 740.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
… …
807Example: Use whatever libev has to offer, but make sure that kqueue is 843Example: Use whatever libev has to offer, but make sure that kqueue is
808used if available. 844used if available.
809.Sp 845.Sp
810.Vb 1 846.Vb 1
811\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE); 847\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
848.Ve
849.Sp
850Example: Similarly, on linux, you mgiht want to take advantage of the
851linux aio backend if possible, but fall back to something else if that
852isn't available.
853.Sp
854.Vb 1
855\& struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_LINUXAIO);
812.Ve 856.Ve
813.RE 857.RE
814.IP "ev_loop_destroy (loop)" 4 858.IP "ev_loop_destroy (loop)" 4
815.IX Item "ev_loop_destroy (loop)" 859.IX Item "ev_loop_destroy (loop)"
816Destroys an event loop object (frees all memory and kernel state 860Destroys an event loop object (frees all memory and kernel state
… …
1748But really, best use non-blocking mode. 1792But really, best use non-blocking mode.
1749.PP 1793.PP
1750\fIThe special problem of disappearing file descriptors\fR 1794\fIThe special problem of disappearing file descriptors\fR
1751.IX Subsection "The special problem of disappearing file descriptors" 1795.IX Subsection "The special problem of disappearing file descriptors"
1752.PP 1796.PP
1753Some backends (e.g. kqueue, epoll) need to be told about closing a file 1797Some 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, 1798a 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 1799means, 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 1800file descriptor, but when it goes away, the operating system will silently
1757this interest. If another file descriptor with the same number then is 1801drop 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 1802is registered with libev, there is no efficient way to see that this is,
1759fact, a different file descriptor. 1803in fact, a different file descriptor.
1760.PP 1804.PP
1761To avoid having to explicitly tell libev about such cases, libev follows 1805To 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 1806the 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 1807will assume that this is potentially a new file descriptor, otherwise
1764it is assumed that the file descriptor stays the same. That means that 1808it is assumed that the file descriptor stays the same. That means that
… …
1816reuse the same code path. 1860reuse the same code path.
1817.PP 1861.PP
1818\fIThe special problem of fork\fR 1862\fIThe special problem of fork\fR
1819.IX Subsection "The special problem of fork" 1863.IX Subsection "The special problem of fork"
1820.PP 1864.PP
1821Some backends (epoll, kqueue) do not support \f(CW\*(C`fork ()\*(C'\fR at all or exhibit 1865Some 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 1866at 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. 1867to be told about it in the child if you want to continue to use it in the
1868child.
1824.PP 1869.PP
1825To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1870To 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 1871()\*(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. 1872\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
1828.PP 1873.PP
… …
4567\& ev_win32.c required on win32 platforms only 4612\& ev_win32.c required on win32 platforms only
4568\& 4613\&
4569\& ev_select.c only when select backend is enabled 4614\& ev_select.c only when select backend is enabled
4570\& ev_poll.c only when poll backend is enabled 4615\& ev_poll.c only when poll backend is enabled
4571\& ev_epoll.c only when the epoll backend is enabled 4616\& ev_epoll.c only when the epoll backend is enabled
4617\& ev_linuxaio.c only when the linux aio backend is enabled
4572\& ev_kqueue.c only when the kqueue backend is enabled 4618\& ev_kqueue.c only when the kqueue backend is enabled
4573\& ev_port.c only when the solaris port backend is enabled 4619\& ev_port.c only when the solaris port backend is enabled
4574.Ve 4620.Ve
4575.PP 4621.PP
4576\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4622\&\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 4803If 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, 4804\&\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 4805otherwise another method will be used as fallback. This is the preferred
4760backend for GNU/Linux systems. If undefined, it will be enabled if the 4806backend for GNU/Linux systems. If undefined, it will be enabled if the
4761headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4807headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4808.IP "\s-1EV_USE_LINUXAIO\s0" 4
4809.IX Item "EV_USE_LINUXAIO"
4810If defined to be \f(CW1\fR, libev will compile in support for the Linux
4811aio backend. Due to it's currenbt limitations it has to be requested
4812explicitly. If undefined, it will be enabled on linux, otherwise
4813disabled.
4762.IP "\s-1EV_USE_KQUEUE\s0" 4 4814.IP "\s-1EV_USE_KQUEUE\s0" 4
4763.IX Item "EV_USE_KQUEUE" 4815.IX Item "EV_USE_KQUEUE"
4764If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4816If 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, 4817\&\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 4818otherwise another method will be used as fallback. This is the preferred

Diff Legend

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