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

Diff Legend

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