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

Comparing libev/ev.3 (file contents):
Revision 1.114 by root, Tue Jun 25 06:36:59 2019 UTC vs.
Revision 1.117 by root, Fri Dec 20 20:51:46 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-25" "libev-4.25" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2019-12-20" "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
… …
589threads that are not interested in handling them. 593threads that are not interested in handling them.
590.Sp 594.Sp
591Signalfd will not be used by default as this changes your signal mask, and 595Signalfd will not be used by default as this changes your signal mask, and
592there are a lot of shoddy libraries and programs (glib's threadpool for 596there are a lot of shoddy libraries and programs (glib's threadpool for
593example) that can't properly initialise their signal masks. 597example) that can't properly initialise their signal masks.
598.ie n .IP """EVFLAG_NOTIMERFD""" 4
599.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4
600.IX Item "EVFLAG_NOTIMERFD"
601When this flag is specified, the libev will avoid using a \f(CW\*(C`timerfd\*(C'\fR to
602detect time jumps. It will still be able to detect time jumps, but takes
603longer and has a lower accuracy in doing so, but saves a file descriptor
604per loop.
594.ie n .IP """EVFLAG_NOSIGMASK""" 4 605.ie n .IP """EVFLAG_NOSIGMASK""" 4
595.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4 606.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4
596.IX Item "EVFLAG_NOSIGMASK" 607.IX Item "EVFLAG_NOSIGMASK"
597When this flag is specified, then libev will avoid to modify the signal 608When this flag is specified, then libev will avoid to modify the signal
598mask. Specifically, this means you have to make sure signals are unblocked 609mask. Specifically, this means you have to make sure signals are unblocked
… …
1650.IX Subsection "WATCHER PRIORITY MODELS" 1661.IX Subsection "WATCHER PRIORITY MODELS"
1651Many event loops support \fIwatcher priorities\fR, which are usually small 1662Many event loops support \fIwatcher priorities\fR, which are usually small
1652integers that influence the ordering of event callback invocation 1663integers that influence the ordering of event callback invocation
1653between watchers in some way, all else being equal. 1664between watchers in some way, all else being equal.
1654.PP 1665.PP
1655In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1666In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1656description for the more technical details such as the actual priority 1667description for the more technical details such as the actual priority
1657range. 1668range.
1658.PP 1669.PP
1659There are two common ways how these these priorities are being interpreted 1670There are two common ways how these these priorities are being interpreted
1660by event loops: 1671by event loops:
… …
1867reuse the same code path. 1878reuse the same code path.
1868.PP 1879.PP
1869\fIThe special problem of fork\fR 1880\fIThe special problem of fork\fR
1870.IX Subsection "The special problem of fork" 1881.IX Subsection "The special problem of fork"
1871.PP 1882.PP
1872Some backends (epoll, kqueue, probably linuxaio) do not support \f(CW\*(C`fork ()\*(C'\fR 1883Some backends (epoll, kqueue, linuxaio, iouring) do not support \f(CW\*(C`fork ()\*(C'\fR
1873at all or exhibit useless behaviour. Libev fully supports fork, but needs 1884at all or exhibit useless behaviour. Libev fully supports fork, but needs
1874to be told about it in the child if you want to continue to use it in the 1885to be told about it in the child if you want to continue to use it in the
1875child. 1886child.
1876.PP 1887.PP
1877To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork 1888To support fork in your child processes, you have to call \f(CW\*(C`ev_loop_fork
… …
4620\& 4631\&
4621\& ev_select.c only when select backend is enabled 4632\& ev_select.c only when select backend is enabled
4622\& ev_poll.c only when poll backend is enabled 4633\& ev_poll.c only when poll backend is enabled
4623\& ev_epoll.c only when the epoll backend is enabled 4634\& ev_epoll.c only when the epoll backend is enabled
4624\& ev_linuxaio.c only when the linux aio backend is enabled 4635\& ev_linuxaio.c only when the linux aio backend is enabled
4636\& ev_iouring.c only when the linux io_uring backend is enabled
4625\& ev_kqueue.c only when the kqueue backend is enabled 4637\& ev_kqueue.c only when the kqueue backend is enabled
4626\& ev_port.c only when the solaris port backend is enabled 4638\& ev_port.c only when the solaris port backend is enabled
4627.Ve 4639.Ve
4628.PP 4640.PP
4629\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4641\&\fIev.c\fR includes the backend files directly when enabled, so you only need
… …
4742higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4754higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4743.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4755.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4744.IX Item "EV_USE_NANOSLEEP" 4756.IX Item "EV_USE_NANOSLEEP"
4745If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4757If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4746and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4758and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4759.IP "\s-1EV_USE_EVENTFD\s0" 4
4760.IX Item "EV_USE_EVENTFD"
4761If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4762available and will probe for kernel support at runtime. This will improve
4763\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4764If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47652.7 or newer, otherwise disabled.
4766.IP "\s-1EV_USE_SIGNALFD\s0" 4
4767.IX Item "EV_USE_SIGNALFD"
4768If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4769available and will probe for kernel support at runtime. This enables
4770the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4771undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47722.7 or newer, otherwise disabled.
4773.IP "\s-1EV_USE_TIMERFD\s0" 4
4774.IX Item "EV_USE_TIMERFD"
4775If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4776available and will probe for kernel support at runtime. This allows
4777libev to detect time jumps accurately. If undefined, it will be enabled
4778if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4779\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4747.IP "\s-1EV_USE_EVENTFD\s0" 4 4780.IP "\s-1EV_USE_EVENTFD\s0" 4
4748.IX Item "EV_USE_EVENTFD" 4781.IX Item "EV_USE_EVENTFD"
4749If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4782If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4750available and will probe for kernel support at runtime. This will improve 4783available and will probe for kernel support at runtime. This will improve
4751\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4784\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
… …
4812otherwise another method will be used as fallback. This is the preferred 4845otherwise another method will be used as fallback. This is the preferred
4813backend for GNU/Linux systems. If undefined, it will be enabled if the 4846backend for GNU/Linux systems. If undefined, it will be enabled if the
4814headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled. 4847headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
4815.IP "\s-1EV_USE_LINUXAIO\s0" 4 4848.IP "\s-1EV_USE_LINUXAIO\s0" 4
4816.IX Item "EV_USE_LINUXAIO" 4849.IX Item "EV_USE_LINUXAIO"
4850If defined to be \f(CW1\fR, libev will compile in support for the Linux aio
4851backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). If undefined, it will be
4852enabled on linux, otherwise disabled.
4853.IP "\s-1EV_USE_IOURING\s0" 4
4854.IX Item "EV_USE_IOURING"
4817If defined to be \f(CW1\fR, libev will compile in support for the Linux 4855If 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 4856io_uring backend (\f(CW\*(C`EV_USE_EPOLL\*(C'\fR must also be enabled). Due to it's
4819explicitly. If undefined, it will be enabled on linux, otherwise 4857current limitations it has to be requested explicitly. If undefined, it
4820disabled. 4858will be enabled on linux, otherwise disabled.
4821.IP "\s-1EV_USE_KQUEUE\s0" 4 4859.IP "\s-1EV_USE_KQUEUE\s0" 4
4822.IX Item "EV_USE_KQUEUE" 4860.IX Item "EV_USE_KQUEUE"
4823If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style 4861If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
4824\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime, 4862\&\f(CW\*(C`kqueue\*(C'\fR(2) backend. Its actual availability will be detected at runtime,
4825otherwise another method will be used as fallback. This is the preferred 4863otherwise another method will be used as fallback. This is the preferred
… …
5081in. If set to \f(CW1\fR, then verification code will be compiled in, but not 5119in. If set to \f(CW1\fR, then verification code will be compiled in, but not
5082called. If set to \f(CW2\fR, then the internal verification code will be 5120called. If set to \f(CW2\fR, then the internal verification code will be
5083called once per loop, which can slow down libev. If set to \f(CW3\fR, then the 5121called once per loop, which can slow down libev. If set to \f(CW3\fR, then the
5084verification code will be called very frequently, which will slow down 5122verification code will be called very frequently, which will slow down
5085libev considerably. 5123libev considerably.
5124.Sp
5125Verification errors are reported via C's \f(CW\*(C`assert\*(C'\fR mechanism, so if you
5126disable that (e.g. by defining \f(CW\*(C`NDEBUG\*(C'\fR) then no errors will be reported.
5086.Sp 5127.Sp
5087The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it 5128The default is \f(CW1\fR, unless \f(CW\*(C`EV_FEATURES\*(C'\fR overrides it, in which case it
5088will be \f(CW0\fR. 5129will be \f(CW0\fR.
5089.IP "\s-1EV_COMMON\s0" 4 5130.IP "\s-1EV_COMMON\s0" 4
5090.IX Item "EV_COMMON" 5131.IX Item "EV_COMMON"

Diff Legend

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