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

Comparing libev/ev.3 (file contents):
Revision 1.108 by root, Sat Jul 28 04:15:15 2018 UTC vs.
Revision 1.109 by root, Fri Dec 21 07:03:02 2018 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 "2017-11-14" "libev-4.24" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2018-12-21" "libev-4.25" "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"
… …
2251.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)" 2251.IX Item "ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)"
2252.PD 0 2252.PD 0
2253.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4 2253.IP "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 4
2254.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)" 2254.IX Item "ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)"
2255.PD 2255.PD
2256Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds. If \f(CW\*(C`repeat\*(C'\fR 2256Configure the timer to trigger after \f(CW\*(C`after\*(C'\fR seconds (fractional and
2257is \f(CW0.\fR, then it will automatically be stopped once the timeout is 2257negative values are supported). If \f(CW\*(C`repeat\*(C'\fR is \f(CW0.\fR, then it will
2258reached. If it is positive, then the timer will automatically be 2258automatically be stopped once the timeout is reached. If it is positive,
2259configured to trigger again \f(CW\*(C`repeat\*(C'\fR seconds later, again, and again, 2259then the timer will automatically be configured to trigger again \f(CW\*(C`repeat\*(C'\fR
2260until stopped manually. 2260seconds later, again, and again, until stopped manually.
2261.Sp 2261.Sp
2262The timer itself will do a best-effort at avoiding drift, that is, if 2262The timer itself will do a best-effort at avoiding drift, that is, if
2263you configure a timer to trigger every 10 seconds, then it will normally 2263you configure a timer to trigger every 10 seconds, then it will normally
2264trigger at exactly 10 second intervals. If, however, your program cannot 2264trigger at exactly 10 second intervals. If, however, your program cannot
2265keep up with the timer (because it takes longer than those 10 seconds to 2265keep up with the timer (because it takes longer than those 10 seconds to
… …
2362\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting 2362\&\f(CW\*(C`ev_timer\*(C'\fR, which would still trigger roughly 10 seconds after starting
2363it, as it uses a relative timeout). 2363it, as it uses a relative timeout).
2364.PP 2364.PP
2365\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex 2365\&\f(CW\*(C`ev_periodic\*(C'\fR watchers can also be used to implement vastly more complex
2366timers, such as triggering an event on each \*(L"midnight, local time\*(R", or 2366timers, such as triggering an event on each \*(L"midnight, local time\*(R", or
2367other complicated rules. This cannot be done with \f(CW\*(C`ev_timer\*(C'\fR watchers, as 2367other complicated rules. This cannot easily be done with \f(CW\*(C`ev_timer\*(C'\fR
2368those cannot react to time jumps. 2368watchers, as those cannot react to time jumps.
2369.PP 2369.PP
2370As with timers, the callback is guaranteed to be invoked only when the 2370As with timers, the callback is guaranteed to be invoked only when the
2371point in time where it is supposed to trigger has passed. If multiple 2371point in time where it is supposed to trigger has passed. If multiple
2372timers become ready during the same loop iteration then the ones with 2372timers become ready during the same loop iteration then the ones with
2373earlier time-out values are invoked before ones with later time-out values 2373earlier time-out values are invoked before ones with later time-out values
… …
2462.Sp 2462.Sp
2463\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or 2463\&\s-1NOTE: \s0\fIThis callback must always return a time that is higher than or
2464equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2464equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2465.Sp 2465.Sp
2466This can be used to create very complex timers, such as a timer that 2466This can be used to create very complex timers, such as a timer that
2467triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate the 2467triggers on \*(L"next midnight, local time\*(R". To do this, you would calculate
2468next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for this. How 2468the next midnight after \f(CW\*(C`now\*(C'\fR and return the timestamp value for
2469you do this is, again, up to you (but it is not trivial, which is the main 2469this. Here is a (completely untested, no error checking) example on how to
2470reason I omitted it as an example). 2470do this:
2471.Sp
2472.Vb 1
2473\& #include <time.h>
2474\&
2475\& static ev_tstamp
2476\& my_rescheduler (ev_periodic *w, ev_tstamp now)
2477\& {
2478\& time_t tnow = (time_t)now;
2479\& struct tm tm;
2480\& localtime_r (&tnow, &tm);
2481\&
2482\& tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2483\& ++tm.tm_mday; // midnight next day
2484\&
2485\& return mktime (&tm);
2486\& }
2487.Ve
2488.Sp
2489Note: this code might run into trouble on days that have more then two
2490midnights (beginning and end).
2471.RE 2491.RE
2472.RS 4 2492.RS 4
2473.RE 2493.RE
2474.IP "ev_periodic_again (loop, ev_periodic *)" 4 2494.IP "ev_periodic_again (loop, ev_periodic *)" 4
2475.IX Item "ev_periodic_again (loop, ev_periodic *)" 2495.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
3645is a time window between the event loop checking and resetting the async 3665is a time window between the event loop checking and resetting the async
3646notification, and the callback being invoked. 3666notification, and the callback being invoked.
3647.SH "OTHER FUNCTIONS" 3667.SH "OTHER FUNCTIONS"
3648.IX Header "OTHER FUNCTIONS" 3668.IX Header "OTHER FUNCTIONS"
3649There are some other functions of possible interest. Described. Here. Now. 3669There are some other functions of possible interest. Described. Here. Now.
3650.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 3670.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)" 4
3651.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 3671.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)"
3652This function combines a simple timer and an I/O watcher, calls your 3672This function combines a simple timer and an I/O watcher, calls your
3653callback on whichever event happens first and automatically stops both 3673callback on whichever event happens first and automatically stops both
3654watchers. This is useful if you want to wait for a single event on an fd 3674watchers. This is useful if you want to wait for a single event on an fd
3655or timeout without having to allocate/configure/start/stop/free one or 3675or timeout without having to allocate/configure/start/stop/free one or
3656more watchers yourself. 3676more watchers yourself.
… …
4106The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the 4126The normal C \s-1API\s0 should work fine when used from \*(C+: both ev.h and the
4107libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4127libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4108will work fine. 4128will work fine.
4109.PP 4129.PP
4110Proper exception specifications might have to be added to callbacks passed 4130Proper exception specifications might have to be added to callbacks passed
4111to libev: exceptions may be thrown only from watcher callbacks, all 4131to libev: exceptions may be thrown only from watcher callbacks, all other
4112other callbacks (allocator, syserr, loop acquire/release and periodic 4132callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4113reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4133callbacks) must not throw exceptions, and might need a \f(CW\*(C`noexcept\*(C'\fR
4114()\*(C'\fR specification. If you have code that needs to be compiled as both C 4134specification. If you have code that needs to be compiled as both C and
4115and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4135\&\*(C+ you can use the \f(CW\*(C`EV_NOEXCEPT\*(C'\fR macro for this:
4116.PP 4136.PP
4117.Vb 6 4137.Vb 6
4118\& static void 4138\& static void
4119\& fatal_error (const char *msg) EV_THROW 4139\& fatal_error (const char *msg) EV_NOEXCEPT
4120\& { 4140\& {
4121\& perror (msg); 4141\& perror (msg);
4122\& abort (); 4142\& abort ();
4123\& } 4143\& }
4124\& 4144\&

Diff Legend

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