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

Comparing libev/ev.3 (file contents):
Revision 1.120 by root, Wed Jan 22 13:33:44 2020 UTC vs.
Revision 1.125 by sf-exg, Sun May 14 19:02:31 2023 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 "2021-01-11" "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"
… …
1087\& \- Queue all expired timers. 1087\& \- Queue all expired timers.
1088\& \- Queue all expired periodics. 1088\& \- Queue all expired periodics.
1089\& \- Queue all idle watchers with priority higher than that of pending events. 1089\& \- Queue all idle watchers with priority higher than that of pending events.
1090\& \- Queue all check watchers. 1090\& \- Queue all check watchers.
1091\& \- Call all queued watchers in reverse order (i.e. check watchers first). 1091\& \- Call all queued watchers in reverse order (i.e. check watchers first).
1092\& Signals and child watchers are implemented as I/O watchers, and will 1092\& Signals, async and child watchers are implemented as I/O watchers, and
1093\& be handled here by queueing them when their watcher gets executed. 1093\& will be handled here by queueing them when their watcher gets executed.
1094\& \- If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT 1094\& \- If ev_break has been called, or EVRUN_ONCE or EVRUN_NOWAIT
1095\& were used, or there are no active watchers, goto FINISH, otherwise 1095\& were used, or there are no active watchers, goto FINISH, otherwise
1096\& continue with step LOOP. 1096\& continue with step LOOP.
1097\& FINISH: 1097\& FINISH:
1098\& \- Reset the ev_break status iff it was EVBREAK_ONE. 1098\& \- Reset the ev_break status iff it was EVBREAK_ONE.
… …
1532therefore 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.
1533.IP "bool ev_is_active (ev_TYPE *watcher)" 4 1533.IP "bool ev_is_active (ev_TYPE *watcher)" 4
1534.IX Item "bool ev_is_active (ev_TYPE *watcher)" 1534.IX Item "bool ev_is_active (ev_TYPE *watcher)"
1535Returns 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
1536and 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
1537it. 1537it unless documented otherwise.
1538.IP "bool ev_is_pending (ev_TYPE *watcher)" 4 1538.IP "bool ev_is_pending (ev_TYPE *watcher)" 4
1539.IX Item "bool ev_is_pending (ev_TYPE *watcher)" 1539.IX Item "bool ev_is_pending (ev_TYPE *watcher)"
1540Returns 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
1541events 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
1542is 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
… …
1772.PP 1772.PP
1773Most members are additionally marked with either \fI[read\-only]\fR, meaning 1773Most members are additionally marked with either \fI[read\-only]\fR, meaning
1774that, 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
1775some 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
1776the 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
1777means 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
1778is 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
1779sensible 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
1780not crash or malfunction in any way. 1781not crash or malfunction in any way.
1781.PP 1782.PP
1782In any case, the documentation for each member will explain what the 1783In any case, the documentation for each member will explain what the
1783effects are, and if there are any additional access restrictions. 1784effects are, and if there are any additional access restrictions.
… …
1964supported, but not specially optimized \- if your program sometimes happens 1965supported, but not specially optimized \- if your program sometimes happens
1965to generate this combination this is fine, but if it is easy to avoid 1966to 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. 1967starting an io watcher watching for no events you should do so.
1967.IP "ev_io_modify (ev_io *, int events)" 4 1968.IP "ev_io_modify (ev_io *, int events)" 4
1968.IX Item "ev_io_modify (ev_io *, int events)" 1969.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 1970Similar to \f(CW\*(C`ev_io_set\*(C'\fR, but only changes the requested events. Using this
1970be 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
1971refers to the same underlying file description, something it cannot do 1972still refers to the same underlying file description, something it cannot
1972when using \f(CW\*(C`ev_io_set\*(C'\fR. 1973do when using \f(CW\*(C`ev_io_set\*(C'\fR.
1973.IP "int fd [no\-modify]" 4 1974.IP "int fd [no\-modify]" 4
1974.IX Item "int fd [no-modify]" 1975.IX Item "int fd [no-modify]"
1975The 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
1976must 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
1977\&\f(CW\*(C`ev_io_set\*(C'\fR for that. 1978\&\f(CW\*(C`ev_io_set\*(C'\fR for that.
… …
4001.PP 4002.PP
4002First, you need to associate some data with the event loop: 4003First, you need to associate some data with the event loop:
4003.PP 4004.PP
4004.Vb 6 4005.Vb 6
4005\& typedef struct { 4006\& typedef struct {
4006\& mutex_t lock; /* global loop lock */ 4007\& pthread_mutex_t lock; /* global loop lock */
4008\& pthread_t tid;
4009\& pthread_cond_t invoke_cv;
4007\& ev_async async_w; 4010\& ev_async async_w;
4008\& thread_t tid;
4009\& cond_t invoke_cv;
4010\& } userdata; 4011\& } userdata;
4011\& 4012\&
4012\& void prepare_loop (EV_P) 4013\& void prepare_loop (EV_P)
4013\& { 4014\& {
4014\& // for simplicity, we use a static userdata struct. 4015\& // for simplicity, we use a static userdata struct.
4015\& static userdata u; 4016\& static userdata u;
4016\& 4017\&
4017\& ev_async_init (&u\->async_w, async_cb); 4018\& ev_async_init (&u.async_w, async_cb);
4018\& ev_async_start (EV_A_ &u\->async_w); 4019\& ev_async_start (EV_A_ &u.async_w);
4019\& 4020\&
4020\& pthread_mutex_init (&u\->lock, 0); 4021\& pthread_mutex_init (&u.lock, 0);
4021\& pthread_cond_init (&u\->invoke_cv, 0); 4022\& pthread_cond_init (&u.invoke_cv, 0);
4022\& 4023\&
4023\& // now associate this with the loop 4024\& // now associate this with the loop
4024\& ev_set_userdata (EV_A_ u); 4025\& ev_set_userdata (EV_A_ &u);
4025\& ev_set_invoke_pending_cb (EV_A_ l_invoke); 4026\& ev_set_invoke_pending_cb (EV_A_ l_invoke);
4026\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); 4027\& ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4027\& 4028\&
4028\& // then create the thread running ev_run 4029\& // then create the thread running ev_run
4029\& pthread_create (&u\->tid, 0, l_run, EV_A); 4030\& pthread_create (&u.tid, 0, l_run, EV_A);
4030\& } 4031\& }
4031.Ve 4032.Ve
4032.PP 4033.PP
4033The 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
4034solely 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
… …
4420.Sp 4421.Sp
4421For \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
4422clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. 4423clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
4423.Sp 4424.Sp
4424For \f(CW\*(C`ev::io\*(C'\fR watchers there is an additional \f(CW\*(C`set\*(C'\fR method that acepts a 4425For \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. 4426new event mask only, and internally calls \f(CW\*(C`ev_io_modify\*(C'\fR.
4426.IP "w\->start ()" 4 4427.IP "w\->start ()" 4
4427.IX Item "w->start ()" 4428.IX Item "w->start ()"
4428Starts 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
4429constructor already stores the event loop. 4430constructor already stores the event loop.
4430.IP "w\->start ([arguments])" 4 4431.IP "w\->start ([arguments])" 4

Diff Legend

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