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

Comparing libev/ev.3 (file contents):
Revision 1.118 by root, Sat Dec 21 16:11:51 2019 UTC vs.
Revision 1.120 by root, Wed Jan 22 13:33:44 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-12-21" "libev-4.31" "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"
… …
1349with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher 1349with a watcher-specific start function (\f(CW\*(C`ev_TYPE_start (loop, watcher
1350*)\*(C'\fR), and you can stop watching for events at any time by calling the 1350*)\*(C'\fR), and you can stop watching for events at any time by calling the
1351corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR. 1351corresponding stop function (\f(CW\*(C`ev_TYPE_stop (loop, watcher *)\*(C'\fR.
1352.PP 1352.PP
1353As long as your watcher is active (has been started but not stopped) you 1353As long as your watcher is active (has been started but not stopped) you
1354must not touch the values stored in it. Most specifically you must never 1354must not touch the values stored in it except when explicitly documented
1355reinitialise it or call its \f(CW\*(C`ev_TYPE_set\*(C'\fR macro. 1355otherwise. Most specifically you must never reinitialise it or call its
1356\&\f(CW\*(C`ev_TYPE_set\*(C'\fR macro.
1356.PP 1357.PP
1357Each and every callback receives the event loop pointer as first, the 1358Each and every callback receives the event loop pointer as first, the
1358registered watcher structure as second, and a bitset of received events as 1359registered watcher structure as second, and a bitset of received events as
1359third argument. 1360third argument.
1360.PP 1361.PP
… …
1767.IX Header "WATCHER TYPES" 1768.IX Header "WATCHER TYPES"
1768This section describes each watcher in detail, but will not repeat 1769This section describes each watcher in detail, but will not repeat
1769information given in the last section. Any initialisation/set macros, 1770information given in the last section. Any initialisation/set macros,
1770functions and members specific to the watcher type are explained. 1771functions and members specific to the watcher type are explained.
1771.PP 1772.PP
1772Members are additionally marked with either \fI[read\-only]\fR, meaning that, 1773Most members are additionally marked with either \fI[read\-only]\fR, meaning
1773while the watcher is active, you can look at the member and expect some 1774that, while the watcher is active, you can look at the member and expect
1774sensible content, but you must not modify it (you can modify it while the 1775some sensible content, but you must not modify it (you can modify it while
1775watcher is stopped to your hearts content), or \fI[read\-write]\fR, which 1776the watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
1776means you can expect it to have some sensible content while the watcher 1777means you can expect it to have some sensible content while the watcher
1777is active, but you can also modify it. Modifying it may not do something 1778is active, but you can also modify it. Modifying it may not do something
1778sensible or take immediate effect (or do anything at all), but libev will 1779sensible or take immediate effect (or do anything at all), but libev will
1779not crash or malfunction in any way. 1780not crash or malfunction in any way.
1781.PP
1782In any case, the documentation for each member will explain what the
1783effects are, and if there are any additional access restrictions.
1780.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" 1784.ie n .SS """ev_io"" \- is this file descriptor readable or writable?"
1781.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" 1785.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1782.IX Subsection "ev_io - is this file descriptor readable or writable?" 1786.IX Subsection "ev_io - is this file descriptor readable or writable?"
1783I/O watchers check whether a file descriptor is readable or writable 1787I/O watchers check whether a file descriptor is readable or writable
1784in each iteration of the event loop, or, more precisely, when reading 1788in each iteration of the event loop, or, more precisely, when reading
… …
1950.PD 0 1954.PD 0
1951.IP "ev_io_set (ev_io *, int fd, int events)" 4 1955.IP "ev_io_set (ev_io *, int fd, int events)" 4
1952.IX Item "ev_io_set (ev_io *, int fd, int events)" 1956.IX Item "ev_io_set (ev_io *, int fd, int events)"
1953.PD 1957.PD
1954Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to 1958Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
1955receive 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 1959receive 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, both
1956\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. 1960\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR or \f(CW0\fR, to express the desire to receive the given
1961events.
1962.Sp
1963Note that setting the \f(CW\*(C`events\*(C'\fR to \f(CW0\fR and starting the watcher is
1964supported, but not specially optimized \- if your program sometimes happens
1965to generate this combination this is fine, but if it is easy to avoid
1966starting an io watcher watching for no events you should do so.
1967.IP "ev_io_modify (ev_io *, int events)" 4
1968.IX Item "ev_io_modify (ev_io *, int events)"
1969Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the event mask. Using this might
1970be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR still
1971refers to the same underlying file description, something it cannot do
1972when using \f(CW\*(C`ev_io_set\*(C'\fR.
1957.IP "int fd [read\-only]" 4 1973.IP "int fd [no\-modify]" 4
1958.IX Item "int fd [read-only]" 1974.IX Item "int fd [no-modify]"
1959The file descriptor being watched. 1975The file descriptor being watched. While it can be read at any time, you
1976must not modify this member even when the watcher is stopped \- always use
1977\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1960.IP "int events [read\-only]" 4 1978.IP "int events [no\-modify]" 4
1961.IX Item "int events [read-only]" 1979.IX Item "int events [no-modify]"
1962The events being watched. 1980The set of events the fd is being watched for, among other flags. Remember
1981that this is a bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events &
1982EV_READ\*(C'\fR, and similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
1983.Sp
1984As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is
1985stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1963.PP 1986.PP
1964\fIExamples\fR 1987\fIExamples\fR
1965.IX Subsection "Examples" 1988.IX Subsection "Examples"
1966.PP 1989.PP
1967Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 1990Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
… …
4395gets automatically stopped and restarted when reconfiguring it with this 4418gets automatically stopped and restarted when reconfiguring it with this
4396method. 4419method.
4397.Sp 4420.Sp
4398For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid 4421For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4399clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. 4422clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4423.Sp
4424For \f(CW\*(C`ev::io\*(C'\fR watchers there is an additional \f(CW\*(C`set\*(C'\fR method that acepts a
4425new event mask only, and internally calls \f(CW\*(C`ev_io_modfify\*(C'\fR.
4400.IP "w\->start ()" 4 4426.IP "w\->start ()" 4
4401.IX Item "w->start ()" 4427.IX Item "w->start ()"
4402Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4428Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4403constructor already stores the event loop. 4429constructor already stores the event loop.
4404.IP "w\->start ([arguments])" 4 4430.IP "w\->start ([arguments])" 4

Diff Legend

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