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

Comparing libev/ev.3 (file contents):
Revision 1.119 by root, Wed Jan 22 02:00:13 2020 UTC vs.
Revision 1.122 by root, Mon Jun 8 11:15:59 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 "2020-01-22" "libev-4.31" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2020-04-19" "libev-4.33" "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
… …
1531therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. 1532therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function.
1532.IP "bool ev_is_active (ev_TYPE *watcher)" 4 1533.IP "bool ev_is_active (ev_TYPE *watcher)" 4
1533.IX Item "bool ev_is_active (ev_TYPE *watcher)" 1534.IX Item "bool ev_is_active (ev_TYPE *watcher)"
1534Returns a true value iff the watcher is active (i.e. it has been started 1535Returns a true value iff the watcher is active (i.e. it has been started
1535and not yet been stopped). As long as a watcher is active you must not modify 1536and not yet been stopped). As long as a watcher is active you must not modify
1536it. 1537it unless documented otherwise.
1537.IP "bool ev_is_pending (ev_TYPE *watcher)" 4 1538.IP "bool ev_is_pending (ev_TYPE *watcher)" 4
1538.IX Item "bool ev_is_pending (ev_TYPE *watcher)" 1539.IX Item "bool ev_is_pending (ev_TYPE *watcher)"
1539Returns a true value iff the watcher is pending, (i.e. it has outstanding 1540Returns a true value iff the watcher is pending, (i.e. it has outstanding
1540events but its callback has not yet been invoked). As long as a watcher 1541events but its callback has not yet been invoked). As long as a watcher
1541is pending (but not active) you must not call an init function on it (but 1542is pending (but not active) you must not call an init function on it (but
… …
1771.PP 1772.PP
1772Most members are additionally marked with either \fI[read\-only]\fR, meaning 1773Most members are additionally marked with either \fI[read\-only]\fR, meaning
1773that, while the watcher is active, you can look at the member and expect 1774that, while the watcher is active, you can look at the member and expect
1774some sensible content, but you must not modify it (you can modify it while 1775some sensible content, but you must not modify it (you can modify it while
1775the watcher 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 is
1777is active, but you can also modify it. Modifying it may not do something 1778active, but you can also modify it (within the same thread as the event
1779loop, i.e. without creating data races). Modifying it may not do something
1778sensible or take immediate effect (or do anything at all), but libev will 1780sensible or take immediate effect (or do anything at all), but libev will
1779not crash or malfunction in any way. 1781not crash or malfunction in any way.
1780.PP 1782.PP
1781In any case, the documentation for each member will explain what the 1783In any case, the documentation for each member will explain what the
1782effects are, and if there are any additional access restrictions. 1784effects are, and if there are any additional access restrictions.
… …
1953.PD 0 1955.PD 0
1954.IP "ev_io_set (ev_io *, int fd, int events)" 4 1956.IP "ev_io_set (ev_io *, int fd, int events)" 4
1955.IX Item "ev_io_set (ev_io *, int fd, int events)" 1957.IX Item "ev_io_set (ev_io *, int fd, int events)"
1956.PD 1958.PD
1957Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to 1959Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
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 1960receive 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
1959\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR, to express the desire to receive the given events. 1961\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR or \f(CW0\fR, to express the desire to receive the given
1962events.
1963.Sp
1964Note that setting the \f(CW\*(C`events\*(C'\fR to \f(CW0\fR and starting the watcher is
1965supported, but not specially optimized \- if your program sometimes happens
1966to generate this combination this is fine, but if it is easy to avoid
1967starting an io watcher watching for no events you should do so.
1960.IP "ev_io_modify (ev_io *, int events)" 4 1968.IP "ev_io_modify (ev_io *, int events)" 4
1961.IX Item "ev_io_modify (ev_io *, int events)" 1969.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 1970Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the requested events. Using this
1963be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR still 1971might be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR
1964refers to the same underlying file description, something it cannot do 1972still refers to the same underlying file description, something it cannot
1965when using \f(CW\*(C`ev_io_set\*(C'\fR. 1973do when using \f(CW\*(C`ev_io_set\*(C'\fR.
1966.IP "int fd [no\-modify]" 4 1974.IP "int fd [no\-modify]" 4
1967.IX Item "int fd [no-modify]" 1975.IX Item "int fd [no-modify]"
1968The file descriptor being watched. While it can be read at any time, you 1976The 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 1977must not modify this member even when the watcher is stopped \- always use
1970\&\f(CW\*(C`ev_io_set\*(C'\fR for that. 1978\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1971.IP "int events [no\-modify]" 4 1979.IP "int events [no\-modify]" 4
1972.IX Item "int events [no-modify]" 1980.IX Item "int events [no-modify]"
1973The set of events being watched, among other flags. This field is a 1981The set of events the fd is being watched for, among other flags. Remember
1974bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events & EV_READ\*(C'\fR, and 1982that this is a bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events &
1975similarly for \f(CW\*(C`EV_WRITE\*(C'\fR. 1983EV_READ\*(C'\fR, and similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
1976.Sp 1984.Sp
1977As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is 1985As 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. 1986stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1979.PP 1987.PP
1980\fIExamples\fR 1988\fIExamples\fR
… …
4411gets automatically stopped and restarted when reconfiguring it with this 4419gets automatically stopped and restarted when reconfiguring it with this
4412method. 4420method.
4413.Sp 4421.Sp
4414For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid 4422For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4415clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. 4423clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4424.Sp
4425For \f(CW\*(C`ev::io\*(C'\fR watchers there is an additional \f(CW\*(C`set\*(C'\fR method that acepts a
4426new event mask only, and internally calls \f(CW\*(C`ev_io_modfify\*(C'\fR.
4416.IP "w\->start ()" 4 4427.IP "w\->start ()" 4
4417.IX Item "w->start ()" 4428.IX Item "w->start ()"
4418Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4429Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4419constructor already stores the event loop. 4430constructor already stores the event loop.
4420.IP "w\->start ([arguments])" 4 4431.IP "w\->start ([arguments])" 4

Diff Legend

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