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

Comparing libev/ev.3 (file contents):
Revision 1.117 by root, Fri Dec 20 20:51:46 2019 UTC vs.
Revision 1.123 by root, Sun Jul 26 11:10:45 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-20" "libev-4.27" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2020-07-12" "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"
… …
593threads that are not interested in handling them. 593threads that are not interested in handling them.
594.Sp 594.Sp
595Signalfd 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
596there 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
597example) that can't properly initialise their signal masks. 597example) that can't properly initialise their signal masks.
598.ie n .IP """EVFLAG_NOSIGMASK""" 4
599.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4
600.IX Item "EVFLAG_NOSIGMASK"
601When this flag is specified, then libev will avoid to modify the signal
602mask. Specifically, this means you have to make sure signals are unblocked
603when you want to receive them.
604.Sp
605This behaviour is useful when you want to do your own signal handling, or
606want to handle signals only in specific threads and want to avoid libev
607unblocking the signals.
608.Sp
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.
598.ie n .IP """EVFLAG_NOTIMERFD""" 4 611.ie n .IP """EVFLAG_NOTIMERFD""" 4
599.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4 612.el .IP "\f(CWEVFLAG_NOTIMERFD\fR" 4
600.IX Item "EVFLAG_NOTIMERFD" 613.IX Item "EVFLAG_NOTIMERFD"
601When this flag is specified, the libev will avoid using a \f(CW\*(C`timerfd\*(C'\fR to 614When 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 615detect 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 616longer and has a lower accuracy in doing so, but saves a file descriptor
604per loop. 617per loop.
605.ie n .IP """EVFLAG_NOSIGMASK""" 4
606.el .IP "\f(CWEVFLAG_NOSIGMASK\fR" 4
607.IX Item "EVFLAG_NOSIGMASK"
608When this flag is specified, then libev will avoid to modify the signal
609mask. Specifically, this means you have to make sure signals are unblocked
610when you want to receive them.
611.Sp 618.Sp
612This behaviour is useful when you want to do your own signal handling, or 619The current implementation only tries to use a \f(CW\*(C`timerfd\*(C'\fR when the first
613want to handle signals only in specific threads and want to avoid libev 620\&\f(CW\*(C`ev_periodic\*(C'\fR watcher is started and falls back on other methods if it
614unblocking the signals. 621cannot be created, but this behaviour might change in the future.
615.Sp
616It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
617\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
618.Sp
619This flag's behaviour will become the default in future versions of libev.
620.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 622.ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4
621.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
622.IX Item "EVBACKEND_SELECT (value 1, portable select backend)" 624.IX Item "EVBACKEND_SELECT (value 1, portable select backend)"
623This 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
624libev 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,
… …
1347with 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
1348*)\*(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
1349corresponding 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.
1350.PP 1352.PP
1351As 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
1352must not touch the values stored in it. Most specifically you must never 1354must not touch the values stored in it except when explicitly documented
1353reinitialise 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.
1354.PP 1357.PP
1355Each and every callback receives the event loop pointer as first, the 1358Each and every callback receives the event loop pointer as first, the
1356registered watcher structure as second, and a bitset of received events as 1359registered watcher structure as second, and a bitset of received events as
1357third argument. 1360third argument.
1358.PP 1361.PP
… …
1529therefore 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.
1530.IP "bool ev_is_active (ev_TYPE *watcher)" 4 1533.IP "bool ev_is_active (ev_TYPE *watcher)" 4
1531.IX Item "bool ev_is_active (ev_TYPE *watcher)" 1534.IX Item "bool ev_is_active (ev_TYPE *watcher)"
1532Returns 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
1533and 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
1534it. 1537it unless documented otherwise.
1535.IP "bool ev_is_pending (ev_TYPE *watcher)" 4 1538.IP "bool ev_is_pending (ev_TYPE *watcher)" 4
1536.IX Item "bool ev_is_pending (ev_TYPE *watcher)" 1539.IX Item "bool ev_is_pending (ev_TYPE *watcher)"
1537Returns 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
1538events 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
1539is 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
… …
1765.IX Header "WATCHER TYPES" 1768.IX Header "WATCHER TYPES"
1766This section describes each watcher in detail, but will not repeat 1769This section describes each watcher in detail, but will not repeat
1767information given in the last section. Any initialisation/set macros, 1770information given in the last section. Any initialisation/set macros,
1768functions and members specific to the watcher type are explained. 1771functions and members specific to the watcher type are explained.
1769.PP 1772.PP
1770Members are additionally marked with either \fI[read\-only]\fR, meaning that, 1773Most members are additionally marked with either \fI[read\-only]\fR, meaning
1771while 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
1772sensible 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
1773watcher 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
1774means 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
1775is 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
1776sensible 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
1777not crash or malfunction in any way. 1781not crash or malfunction in any way.
1782.PP
1783In any case, the documentation for each member will explain what the
1784effects are, and if there are any additional access restrictions.
1778.ie n .SS """ev_io"" \- is this file descriptor readable or writable?" 1785.ie n .SS """ev_io"" \- is this file descriptor readable or writable?"
1779.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?" 1786.el .SS "\f(CWev_io\fP \- is this file descriptor readable or writable?"
1780.IX Subsection "ev_io - is this file descriptor readable or writable?" 1787.IX Subsection "ev_io - is this file descriptor readable or writable?"
1781I/O watchers check whether a file descriptor is readable or writable 1788I/O watchers check whether a file descriptor is readable or writable
1782in each iteration of the event loop, or, more precisely, when reading 1789in each iteration of the event loop, or, more precisely, when reading
… …
1948.PD 0 1955.PD 0
1949.IP "ev_io_set (ev_io *, int fd, int events)" 4 1956.IP "ev_io_set (ev_io *, int fd, int events)" 4
1950.IX Item "ev_io_set (ev_io *, int fd, int events)" 1957.IX Item "ev_io_set (ev_io *, int fd, int events)"
1951.PD 1958.PD
1952Configures 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
1953receive 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
1954\&\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.
1968.IP "ev_io_modify (ev_io *, int events)" 4
1969.IX Item "ev_io_modify (ev_io *, int events)"
1970Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the requested events. Using this
1971might be faster with some backends, as libev can assume that the \f(CW\*(C`fd\*(C'\fR
1972still refers to the same underlying file description, something it cannot
1973do when using \f(CW\*(C`ev_io_set\*(C'\fR.
1955.IP "int fd [read\-only]" 4 1974.IP "int fd [no\-modify]" 4
1956.IX Item "int fd [read-only]" 1975.IX Item "int fd [no-modify]"
1957The file descriptor being watched. 1976The file descriptor being watched. While it can be read at any time, you
1977must not modify this member even when the watcher is stopped \- always use
1978\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
1958.IP "int events [read\-only]" 4 1979.IP "int events [no\-modify]" 4
1959.IX Item "int events [read-only]" 1980.IX Item "int events [no-modify]"
1960The events being watched. 1981The set of events the fd is being watched for, among other flags. Remember
1982that this is a bit set \- to test for \f(CW\*(C`EV_READ\*(C'\fR, use \f(CW\*(C`w\->events &
1983EV_READ\*(C'\fR, and similarly for \f(CW\*(C`EV_WRITE\*(C'\fR.
1984.Sp
1985As with \f(CW\*(C`fd\*(C'\fR, you must not modify this member even when the watcher is
1986stopped, always use \f(CW\*(C`ev_io_set\*(C'\fR or \f(CW\*(C`ev_io_modify\*(C'\fR for that.
1961.PP 1987.PP
1962\fIExamples\fR 1988\fIExamples\fR
1963.IX Subsection "Examples" 1989.IX Subsection "Examples"
1964.PP 1990.PP
1965Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 1991Example: Call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
… …
3976.PP 4002.PP
3977First, you need to associate some data with the event loop: 4003First, you need to associate some data with the event loop:
3978.PP 4004.PP
3979.Vb 6 4005.Vb 6
3980\& typedef struct { 4006\& typedef struct {
3981\& mutex_t lock; /* global loop lock */ 4007\& pthread_mutex_t lock; /* global loop lock */
4008\& pthread_t tid;
4009\& pthread_cond_t invoke_cv;
3982\& ev_async async_w; 4010\& ev_async async_w;
3983\& thread_t tid;
3984\& cond_t invoke_cv;
3985\& } userdata; 4011\& } userdata;
3986\& 4012\&
3987\& void prepare_loop (EV_P) 4013\& void prepare_loop (EV_P)
3988\& { 4014\& {
3989\& // for simplicity, we use a static userdata struct. 4015\& // for simplicity, we use a static userdata struct.
3990\& static userdata u; 4016\& static userdata u;
3991\& 4017\&
3992\& ev_async_init (&u\->async_w, async_cb); 4018\& ev_async_init (&u.async_w, async_cb);
3993\& ev_async_start (EV_A_ &u\->async_w); 4019\& ev_async_start (EV_A_ &u.async_w);
3994\& 4020\&
3995\& pthread_mutex_init (&u\->lock, 0); 4021\& pthread_mutex_init (&u.lock, 0);
3996\& pthread_cond_init (&u\->invoke_cv, 0); 4022\& pthread_cond_init (&u.invoke_cv, 0);
3997\& 4023\&
3998\& // now associate this with the loop 4024\& // now associate this with the loop
3999\& ev_set_userdata (EV_A_ u); 4025\& ev_set_userdata (EV_A_ &u);
4000\& ev_set_invoke_pending_cb (EV_A_ l_invoke); 4026\& ev_set_invoke_pending_cb (EV_A_ l_invoke);
4001\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 4027\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4002\& 4028\&
4003\& // then create the thread running ev_run 4029\& // then create the thread running ev_run
4004\& pthread_create (&u\->tid, 0, l_run, EV_A); 4030\& pthread_create (&u.tid, 0, l_run, EV_A);
4005\& } 4031\& }
4006.Ve 4032.Ve
4007.PP 4033.PP
4008The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used 4034The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used
4009solely to wake up the event loop so it takes notice of any new watchers 4035solely to wake up the event loop so it takes notice of any new watchers
… …
4393gets automatically stopped and restarted when reconfiguring it with this 4419gets automatically stopped and restarted when reconfiguring it with this
4394method. 4420method.
4395.Sp 4421.Sp
4396For \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
4397clashing 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.
4398.IP "w\->start ()" 4 4427.IP "w\->start ()" 4
4399.IX Item "w->start ()" 4428.IX Item "w->start ()"
4400Starts 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
4401constructor already stores the event loop. 4430constructor already stores the event loop.
4402.IP "w\->start ([arguments])" 4 4431.IP "w\->start ([arguments])" 4

Diff Legend

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