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

Comparing libev/ev.3 (file contents):
Revision 1.111 by root, Sun Jun 23 02:02:24 2019 UTC vs.
Revision 1.116 by root, Sun Jul 7 06:00:32 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-22" "libev-4.25" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-07-07" "libev-4.27" "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"
… …
291When libev detects a usage error such as a negative timer interval, then 291When libev detects a usage error such as a negative timer interval, then
292it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism, 292it will print a diagnostic message and abort (via the \f(CW\*(C`assert\*(C'\fR mechanism,
293so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in 293so \f(CW\*(C`NDEBUG\*(C'\fR will disable this checking): these are programming errors in
294the libev caller and need to be fixed there. 294the libev caller and need to be fixed there.
295.PP 295.PP
296Via the \f(CW\*(C`EV_FREQUENT\*(C'\fR macro you can compile in and/or enable extensive
297consistency checking code inside libev that can be used to check for
298internal inconsistencies, suually caused by application bugs.
299.PP
296Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions, and also has 300Libev also has a few internal error-checking \f(CW\*(C`assert\*(C'\fRions. These do not
297extensive consistency checking code. These do not trigger under normal
298circumstances, as they indicate either a bug in libev or worse. 301trigger under normal circumstances, as they indicate either a bug in libev
302or worse.
299.SH "GLOBAL FUNCTIONS" 303.SH "GLOBAL FUNCTIONS"
300.IX Header "GLOBAL FUNCTIONS" 304.IX Header "GLOBAL FUNCTIONS"
301These functions can be called anytime, even before initialising the 305These functions can be called anytime, even before initialising the
302library in any way. 306library in any way.
303.IP "ev_tstamp ev_time ()" 4 307.IP "ev_tstamp ev_time ()" 4
… …
638This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and 642This 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. 643\&\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 644.ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4
641.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 645.el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4
642.IX Item "EVBACKEND_EPOLL (value 4, Linux)" 646.IX Item "EVBACKEND_EPOLL (value 4, Linux)"
643Use the linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 647Use the Linux-specific \fBepoll\fR\|(7) interface (for both pre\- and post\-2.6.9
644kernels). 648kernels).
645.Sp 649.Sp
646For few fds, this backend is a bit little slower than poll and select, but 650For 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 651it 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 652O(total_fds) where total_fds is the total number of fds (or the highest
… …
701This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 705This 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. 706\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
703.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4 707.ie n .IP """EVBACKEND_LINUXAIO"" (value 64, Linux)" 4
704.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4 708.el .IP "\f(CWEVBACKEND_LINUXAIO\fR (value 64, Linux)" 4
705.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)" 709.IX Item "EVBACKEND_LINUXAIO (value 64, Linux)"
706Use the linux-specific linux aio (\fInot\fR \f(CWaio(7)\fR) event interface 710Use 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
707available in post\-4.18 kernels. 711only tries to use it in 4.19+).
712.Sp
713This is another Linux train wreck of an event interface.
708.Sp 714.Sp
709If this backend works for you (as of this writing, it was very 715If 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 716experimental), it is the best event interface available on Linux and might
711event interface available on linux and might be well worth it enabling it 717be well worth enabling it \- if it isn't available in your kernel this will
712\&\- if it isn't available in your kernel this will be detected and another 718be detected and this backend will be skipped.
713backend will be chosen.
714.Sp 719.Sp
715This backend can batch oneshot requests and uses a user-space ring buffer 720This backend can batch oneshot requests and supports a user-space ring
716to receive events. It also doesn't suffer from most of the design problems 721buffer to receive events. It also doesn't suffer from most of the design
717of epoll (such as not being able to remove event sources from the epoll 722problems of epoll (such as not being able to remove event sources from
718set), and generally sounds too good to be true. Because, this being the 723the epoll set), and generally sounds too good to be true. Because, this
719linux kernel, of course it suffers from a whole new set of limitations. 724being the Linux kernel, of course it suffers from a whole new set of
725limitations, forcing you to fall back to epoll, inheriting all its design
726issues.
720.Sp 727.Sp
721For one, it is not easily embeddable (but probably could be done using 728For 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 729an event fd at some extra overhead). It also is subject to a system wide
723arbitrary limits that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR 730limit that can be configured in \fI/proc/sys/fs/aio\-max\-nr\fR. If no \s-1AIO\s0
724and \fI/proc/sys/fs/aio\-nr\fR), which could lead to it being skipped during 731requests are left, this backend will be skipped during initialisation, and
725initialisation. 732will switch to epoll when the loop is active.
726.Sp 733.Sp
727Most problematic in practise, however, is that, like kqueue, it requires 734Most problematic in practice, however, is that not all file descriptors
728special support from drivers, and, not surprisingly, not all drivers
729implement it. For example, in linux 4.19, tcp sockets, pipes, event fds, 735work with it. For example, in Linux 5.1, \s-1TCP\s0 sockets, pipes, event fds,
730files, \fI/dev/null\fR and a few others are supported, but ttys are not, so 736files, \fI/dev/null\fR and many others are supported, but ttys do not work
731this is not (yet?) a generic event polling interface but is probably still 737properly (a known bug that the kernel developers don't care about, see
732be very useful in a web server or similar program. 738<https://lore.kernel.org/patchwork/patch/1047453/>), so this is not
739(yet?) a generic event polling interface.
740.Sp
741Overall, it seems the Linux developers just don't want it to have a
742generic event handling mechanism other than \f(CW\*(C`select\*(C'\fR or \f(CW\*(C`poll\*(C'\fR.
743.Sp
744To work around all these problem, the current version of libev uses its
745epoll backend as a fallback for file descriptor types that do not work. Or
746falls back completely to epoll if the kernel acts up.
733.Sp 747.Sp
734This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as 748This backend maps \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR in the same way as
735\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR. 749\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR.
736.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4 750.ie n .IP """EVBACKEND_KQUEUE"" (value 8, most \s-1BSD\s0 clones)" 4
737.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4 751.el .IP "\f(CWEVBACKEND_KQUEUE\fR (value 8, most \s-1BSD\s0 clones)" 4
738.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)" 752.IX Item "EVBACKEND_KQUEUE (value 8, most BSD clones)"
739Kqueue deserves special mention, as at the time of this writing, it 753Kqueue deserves special mention, as at the time this backend was
740was broken on all BSDs except NetBSD (usually it doesn't work reliably 754implemented, it was broken on all BSDs except NetBSD (usually it doesn't
741with anything but sockets and pipes, except on Darwin, where of course 755work reliably with anything but sockets and pipes, except on Darwin,
742it's completely useless). Unlike epoll, however, whose brokenness 756where of course it's completely useless). Unlike epoll, however, whose
743is by design, these kqueue bugs can (and eventually will) be fixed 757brokenness is by design, these kqueue bugs can be (and mostly have been)
744without \s-1API\s0 changes to existing programs. For this reason it's not being 758fixed without \s-1API\s0 changes to existing programs. For this reason it's not
745\&\*(L"auto-detected\*(R" unless you explicitly specify it in the flags (i.e. using 759being \*(L"auto-detected\*(R" on all platforms unless you explicitly specify it
746\&\f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a known-to-be-good (\-enough) 760in the flags (i.e. using \f(CW\*(C`EVBACKEND_KQUEUE\*(C'\fR) or libev was compiled on a
747system like NetBSD. 761known-to-be-good (\-enough) system like NetBSD.
748.Sp 762.Sp
749You still can embed kqueue into a normal poll or select backend and use it 763You still can embed kqueue into a normal poll or select backend and use it
750only for sockets (after having made sure that sockets work with kqueue on 764only for sockets (after having made sure that sockets work with kqueue on
751the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info. 765the target platform). See \f(CW\*(C`ev_embed\*(C'\fR watchers for more info.
752.Sp 766.Sp
753It scales in the same way as the epoll backend, but the interface to the 767It scales in the same way as the epoll backend, but the interface to the
754kernel is more efficient (which says nothing about its actual speed, of 768kernel is more efficient (which says nothing about its actual speed, of
755course). While stopping, setting and starting an I/O watcher does never 769course). While stopping, setting and starting an I/O watcher does never
756cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 770cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
757two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you 771two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
758might have to leak fd's on fork, but it's more sane than epoll) and it 772might have to leak fds on fork, but it's more sane than epoll) and it
759drops fds silently in similarly hard-to-detect cases. 773drops fds silently in similarly hard-to-detect cases.
760.Sp 774.Sp
761This backend usually performs well under most conditions. 775This backend usually performs well under most conditions.
762.Sp 776.Sp
763While nominally embeddable in other event loops, this doesn't work 777While nominally embeddable in other event loops, this doesn't work
… …
1857reuse the same code path. 1871reuse the same code path.
1858.PP 1872.PP
1859\fIThe special problem of fork\fR 1873\fIThe special problem of fork\fR
1860.IX Subsection "The special problem of fork" 1874.IX Subsection "The special problem of fork"
1861.PP 1875.PP
1862Some backends (epoll, kqueue, probably linuxaio) do not support \f(CW\*(C`fork ()\*(C'\fR 1876Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1863at all or exhibit useless behaviour. Libev fully supports fork, but needs 1877at all or exhibit useless behaviour. Libev fully supports fork, but needs
1864to be told about it in the child if you want to continue to use it in the 1878to be told about it in the child if you want to continue to use it in the
1865child. 1879child.
1866.PP 1880.PP
1867To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1881To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
… …
4610\& 4624\&
4611\& ev_select.c only when select backend is enabled 4625\& ev_select.c only when select backend is enabled
4612\& ev_poll.c only when poll backend is enabled 4626\& ev_poll.c only when poll backend is enabled
4613\& ev_epoll.c only when the epoll backend is enabled 4627\& ev_epoll.c only when the epoll backend is enabled
4614\& ev_linuxaio.c only when the linux aio backend is enabled 4628\& ev_linuxaio.c only when the linux aio backend is enabled
4629\& ev_iouring.c only when the linux io_uring backend is enabled
4615\& ev_kqueue.c only when the kqueue backend is enabled 4630\& ev_kqueue.c only when the kqueue backend is enabled
4616\& ev_port.c only when the solaris port backend is enabled 4631\& ev_port.c only when the solaris port backend is enabled
4617.Ve 4632.Ve
4618.PP 4633.PP
4619\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4634\&\fIev.c\fR includes the backend files directly when enabled, so you only need
… …
4802otherwise another method will be used as fallback. This is the preferred 4817otherwise another method will be used as fallback. This is the preferred
4803backend for GNU/Linux systems. If undefined, it will be enabled if the 4818backend for GNU/Linux systems. If undefined, it will be enabled if the
4804headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4819headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4805.IP "\s-1EV_USE_LINUXAIO\s0" 4 4820.IP "\s-1EV_USE_LINUXAIO\s0" 4
4806.IX Item "EV_USE_LINUXAIO" 4821.IX Item "EV_USE_LINUXAIO"
4822If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4823backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4824enabled on linux, otherwise disabled.
4825.IP "\s-1EV_USE_IOURING\s0" 4
4826.IX Item "EV_USE_IOURING"
4807If defined to be \f(CW1\fR, libev will compile in support for the Linux 4827If 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 4828io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4809explicitly. If undefined, it will be enabled on linux, otherwise 4829current limitations it has to be requested explicitly. If undefined, it
4810disabled. 4830will be enabled on linux, otherwise disabled.
4811.IP "\s-1EV_USE_KQUEUE\s0" 4 4831.IP "\s-1EV_USE_KQUEUE\s0" 4
4812.IX Item "EV_USE_KQUEUE" 4832.IX Item "EV_USE_KQUEUE"
4813If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4833If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4814\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4834\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4815otherwise another method will be used as fallback. This is the preferred 4835otherwise another method will be used as fallback. This is the preferred
… …
5071in. If set to \f(CW1\fR, then verification code will be compiled in, but not 5091in. If set to \f(CW1\fR, then verification code will be compiled in, but not
5072called. If set to \f(CW2\fR, then the internal verification code will be 5092called. If set to \f(CW2\fR, then the internal verification code will be
5073called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5093called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
5074verification code will be called very frequently, which will slow down 5094verification code will be called very frequently, which will slow down
5075libev considerably. 5095libev considerably.
5096.Sp
5097Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5098disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5076.Sp 5099.Sp
5077The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5100The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
5078will be \f(CW0\fR. 5101will be \f(CW0\fR.
5079.IP "\s-1EV_COMMON\s0" 4 5102.IP "\s-1EV_COMMON\s0" 4
5080.IX Item "EV_COMMON" 5103.IX Item "EV_COMMON"

Diff Legend

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