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

Comparing libev/ev.3 (file contents):
Revision 1.116 by root, Sun Jul 7 06:00:32 2019 UTC vs.
Revision 1.119 by root, Wed Jan 22 02:00:13 2020 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-07-07" "libev-4.27" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2020-01-22" "libev-4.31" "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"
… …
606want to handle signals only in specific threads and want to avoid libev 606want to handle signals only in specific threads and want to avoid libev
607unblocking the signals. 607unblocking the signals.
608.Sp 608.Sp
609It's also required by \s-1POSIX\s0 in a threaded program, as libev calls 609It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
610\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. 610\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
611.ie n .IP """EVFLAG_NOTIMERFD""" 4
612.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4
613.IX Item "EVFLAG_NOTIMERFD"
614When this flag is specified, the libev will avoid using a \f(CW\*(C`timerfd\*(C'\fR to
615detect time jumps. It will still be able to detect time jumps, but takes
616longer and has a lower accuracy in doing so, but saves a file descriptor
617per loop.
611.Sp 618.Sp
612This flag's behaviour will become the default in future versions of libev. 619The current implementation only tries to use a \f(CW\*(C`timerfd\*(C'\fR when the first
620\&\f(CW\*(C`ev_periodic\*(C'\fR watcher is started and falls back on other methods if it
621cannot be created, but this behaviour might change in the future.
613.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 622.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
614.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 623.el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4
615.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 624.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
616This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as 625This is your standard \fBselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
617libev tries to roll its own fd_set with no limits on the number of fds, 626libev tries to roll its own fd_set with no limits on the number of fds,
… …
1654.IX Subsection "WATCHER PRIORITY MODELS" 1663.IX Subsection "WATCHER PRIORITY MODELS"
1655Many event loops support \fIwatcher priorities\fR, which are usually small 1664Many event loops support \fIwatcher priorities\fR, which are usually small
1656integers that influence the ordering of event callback invocation 1665integers that influence the ordering of event callback invocation
1657between watchers in some way, all else being equal. 1666between watchers in some way, all else being equal.
1658.PP 1667.PP
1659In libev, Watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its 1668In libev, watcher priorities can be set using \f(CW\*(C`ev_set_priority\*(C'\fR. See its
1660description for the more technical details such as the actual priority 1669description for the more technical details such as the actual priority
1661range. 1670range.
1662.PP 1671.PP
1663There are two common ways how these these priorities are being interpreted 1672There are two common ways how these these priorities are being interpreted
1664by event loops: 1673by event loops:
… …
1758.IX Header "WATCHER TYPES" 1767.IX Header "WATCHER TYPES"
1759This section describes each watcher in detail, but will not repeat 1768This section describes each watcher in detail, but will not repeat
1760information given in the last section. Any initialisation/set macros, 1769information given in the last section. Any initialisation/set macros,
1761functions and members specific to the watcher type are explained. 1770functions and members specific to the watcher type are explained.
1762.PP 1771.PP
1763Members are additionally marked with either \fI[read\-only]\fR, meaning that, 1772Most members are additionally marked with either \fI[read\-only]\fR, meaning
1764while the watcher is active, you can look at the member and expect some 1773that, while the watcher is active, you can look at the member and expect
1765sensible content, but you must not modify it (you can modify it while the 1774some sensible content, but you must not modify it (you can modify it while
1766watcher is stopped to your hearts content), or \fI[read\-write]\fR, which 1775the watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
1767means you can expect it to have some sensible content while the watcher 1776means you can expect it to have some sensible content while the watcher
1768is active, but you can also modify it. Modifying it may not do something 1777is active, but you can also modify it. Modifying it may not do something
1769sensible or take immediate effect (or do anything at all), but libev will 1778sensible or take immediate effect (or do anything at all), but libev will
1770not crash or malfunction in any way. 1779not crash or malfunction in any way.
1780.PP
1781In any case, the documentation for each member will explain what the
1782effects are, and if there are any additional access restrictions.
1771.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" 1783.ie n .SS """ev_io"" \- is this file descriptor readable or writable?"
1772.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" 1784.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1773.IX Subsection "ev_io - is this file descriptor readable or writable?" 1785.IX Subsection "ev_io - is this file descriptor readable or writable?"
1774I/O watchers check whether a file descriptor is readable or writable 1786I/O watchers check whether a file descriptor is readable or writable
1775in each iteration of the event loop, or, more precisely, when reading 1787in each iteration of the event loop, or, more precisely, when reading
… …
1943.IX Item "ev_io_set (ev_io *, int fd, int events)" 1955.IX Item "ev_io_set (ev_io *, int fd, int events)"
1944.PD 1956.PD
1945Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to 1957Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
1946receive events for and \f(CW\*(C`events\*(C'\fR is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or 1958receive events for and \f(CW\*(C`events\*(C'\fR is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or
1947\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. 1959\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events.
1960.IP "ev_io_modify (ev_io *, int events)" 4
1961.IX Item "ev_io_modify (ev_io *, int events)"
1962Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the event mask. Using this might
1963be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR still
1964refers to the same underlying file description, something it cannot do
1965when using \f(CW\*(C`ev_io_set\*(C'\fR.
1948.IP "int fd [read\-only]" 4 1966.IP "int fd [no\-modify]" 4
1949.IX Item "int fd [read-only]" 1967.IX Item "int fd [no-modify]"
1950The file descriptor being watched. 1968The file descriptor being watched. While it can be read at any time, you
1969must not modify this member even when the watcher is stopped \- always use
1970\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1951.IP "int events [read\-only]" 4 1971.IP "int events [no\-modify]" 4
1952.IX Item "int events [read-only]" 1972.IX Item "int events [no-modify]"
1953The events being watched. 1973The set of events being watched, among other flags. This field is a
1974bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events & EV_READ\*(C'\fR, and
1975similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
1976.Sp
1977As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is
1978stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1954.PP 1979.PP
1955\fIExamples\fR 1980\fIExamples\fR
1956.IX Subsection "Examples" 1981.IX Subsection "Examples"
1957.PP 1982.PP
1958Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 1983Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
… …
4747higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). 4772higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR).
4748.IP "\s-1EV_USE_NANOSLEEP\s0" 4 4773.IP "\s-1EV_USE_NANOSLEEP\s0" 4
4749.IX Item "EV_USE_NANOSLEEP" 4774.IX Item "EV_USE_NANOSLEEP"
4750If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available 4775If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available
4751and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. 4776and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR.
4777.IP "\s-1EV_USE_EVENTFD\s0" 4
4778.IX Item "EV_USE_EVENTFD"
4779If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4780available and will probe for kernel support at runtime. This will improve
4781\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.
4782If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47832.7 or newer, otherwise disabled.
4784.IP "\s-1EV_USE_SIGNALFD\s0" 4
4785.IX Item "EV_USE_SIGNALFD"
4786If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`signalfd ()\*(C'\fR is
4787available and will probe for kernel support at runtime. This enables
4788the use of \s-1EVFLAG_SIGNALFD\s0 for faster and simpler signal handling. If
4789undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
47902.7 or newer, otherwise disabled.
4791.IP "\s-1EV_USE_TIMERFD\s0" 4
4792.IX Item "EV_USE_TIMERFD"
4793If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`timerfd ()\*(C'\fR is
4794available and will probe for kernel support at runtime. This allows
4795libev to detect time jumps accurately. If undefined, it will be enabled
4796if the headers indicate GNU/Linux + Glibc 2.8 or newer and define
4797\&\f(CW\*(C`TFD_TIMER_CANCEL_ON_SET\*(C'\fR, otherwise disabled.
4752.IP "\s-1EV_USE_EVENTFD\s0" 4 4798.IP "\s-1EV_USE_EVENTFD\s0" 4
4753.IX Item "EV_USE_EVENTFD" 4799.IX Item "EV_USE_EVENTFD"
4754If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is 4800If defined to be \f(CW1\fR, then libev will assume that \f(CW\*(C`eventfd ()\*(C'\fR is
4755available and will probe for kernel support at runtime. This will improve 4801available and will probe for kernel support at runtime. This will improve
4756\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption. 4802\&\f(CW\*(C`ev_signal\*(C'\fR and \f(CW\*(C`ev_async\*(C'\fR performance and reduce resource consumption.

Diff Legend

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