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

Comparing libev/ev.3 (file contents):
Revision 1.103 by root, Fri May 1 17:23:34 2015 UTC vs.
Revision 1.109 by root, Fri Dec 21 07:03:02 2018 UTC

1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) 1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
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 "2015-05-01" "libev-4.19" "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"
… …
536make libev check for a fork in each iteration by enabling this flag. 536make libev check for a fork in each iteration by enabling this flag.
537.Sp 537.Sp
538This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, 538This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop,
539and thus this might slow down your event loop if you do a lot of loop 539and thus this might slow down your event loop if you do a lot of loop
540iterations and little real work, but is usually not noticeable (on my 540iterations and little real work, but is usually not noticeable (on my
541GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence 541GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn
542without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has 542sequence without a system call and thus \fIvery\fR fast, but my GNU/Linux
543\&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). 543system also has \f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). (Update: glibc
544versions 2.25 apparently removed the \f(CW\*(C`getpid\*(C'\fR optimisation again).
544.Sp 545.Sp
545The big advantage of this flag is that you can forget about fork (and 546The big advantage of this flag is that you can forget about fork (and
546forget about forgetting to tell libev about forking) when you use this 547forget about forgetting to tell libev about forking, although you still
547flag. 548have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
548.Sp 549.Sp
549This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR 550This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
550environment variable. 551environment variable.
551.ie n .IP """EVFLAG_NOINOTIFY""" 4 552.ie n .IP """EVFLAG_NOINOTIFY""" 4
552.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 553.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
… …
816to reinitialise the kernel state for backends that have one. Despite 817to reinitialise the kernel state for backends that have one. Despite
817the name, you can call it anytime you are allowed to start or stop 818the name, you can call it anytime you are allowed to start or stop
818watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most 819watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
819sense after forking, in the child process. You \fImust\fR call it (or use 820sense after forking, in the child process. You \fImust\fR call it (or use
820\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 821\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
822.Sp
823In addition, if you want to reuse a loop (via this function or
824\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
821.Sp 825.Sp
822Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 826Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
823a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is 827a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
824because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 828because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
825during fork. 829during fork.
… …
2247.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)"
2248.PD 0 2252.PD 0
2249.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
2250.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)"
2251.PD 2255.PD
2252Configure 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
2253is \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
2254reached. If it is positive, then the timer will automatically be 2258automatically be stopped once the timeout is reached. If it is positive,
2255configured 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
2256until stopped manually. 2260seconds later, again, and again, until stopped manually.
2257.Sp 2261.Sp
2258The 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
2259you 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
2260trigger at exactly 10 second intervals. If, however, your program cannot 2264trigger at exactly 10 second intervals. If, however, your program cannot
2261keep 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
… …
2343Periodic watchers are also timers of a kind, but they are very versatile 2347Periodic watchers are also timers of a kind, but they are very versatile
2344(and unfortunately a bit complex). 2348(and unfortunately a bit complex).
2345.PP 2349.PP
2346Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or 2350Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
2347relative time, the physical time that passes) but on wall clock time 2351relative time, the physical time that passes) but on wall clock time
2348(absolute time, the thing you can read on your calender or clock). The 2352(absolute time, the thing you can read on your calendar or clock). The
2349difference is that wall clock time can run faster or slower than real 2353difference is that wall clock time can run faster or slower than real
2350time, and time jumps are not uncommon (e.g. when you adjust your 2354time, and time jumps are not uncommon (e.g. when you adjust your
2351wrist-watch). 2355wrist-watch).
2352.PP 2356.PP
2353You can tell a periodic watcher to trigger after some specific point 2357You can tell a periodic watcher to trigger after some specific point
… …
2358\&\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
2359it, as it uses a relative timeout). 2363it, as it uses a relative timeout).
2360.PP 2364.PP
2361\&\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
2362timers, 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
2363other 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
2364those cannot react to time jumps. 2368watchers, as those cannot react to time jumps.
2365.PP 2369.PP
2366As 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
2367point 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
2368timers become ready during the same loop iteration then the ones with 2372timers become ready during the same loop iteration then the ones with
2369earlier 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
… …
2458.Sp 2462.Sp
2459\&\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
2460equal to the passed \f(CI\*(C`now\*(C'\fI value\fR. 2464equal to the passed \f(CI\*(C`now\*(C'\fI value\fR.
2461.Sp 2465.Sp
2462This 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
2463triggers 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
2464next 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
2465you 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
2466reason 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).
2467.RE 2491.RE
2468.RS 4 2492.RS 4
2469.RE 2493.RE
2470.IP "ev_periodic_again (loop, ev_periodic *)" 4 2494.IP "ev_periodic_again (loop, ev_periodic *)" 4
2471.IX Item "ev_periodic_again (loop, ev_periodic *)" 2495.IX Item "ev_periodic_again (loop, ev_periodic *)"
… …
3641is 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
3642notification, and the callback being invoked. 3666notification, and the callback being invoked.
3643.SH "OTHER FUNCTIONS" 3667.SH "OTHER FUNCTIONS"
3644.IX Header "OTHER FUNCTIONS" 3668.IX Header "OTHER FUNCTIONS"
3645There are some other functions of possible interest. Described. Here. Now. 3669There are some other functions of possible interest. Described. Here. Now.
3646.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
3647.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)"
3648This 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
3649callback on whichever event happens first and automatically stops both 3673callback on whichever event happens first and automatically stops both
3650watchers. 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
3651or timeout without having to allocate/configure/start/stop/free one or 3675or timeout without having to allocate/configure/start/stop/free one or
3652more watchers yourself. 3676more watchers yourself.
… …
4102The 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
4103libev 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
4104will work fine. 4128will work fine.
4105.PP 4129.PP
4106Proper exception specifications might have to be added to callbacks passed 4130Proper exception specifications might have to be added to callbacks passed
4107to libev: exceptions may be thrown only from watcher callbacks, all 4131to libev: exceptions may be thrown only from watcher callbacks, all other
4108other callbacks (allocator, syserr, loop acquire/release and periodic 4132callbacks (allocator, syserr, loop acquire/release and periodic reschedule
4109reschedule 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
4110()\*(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
4111and \*(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:
4112.PP 4136.PP
4113.Vb 6 4137.Vb 6
4114\& static void 4138\& static void
4115\& fatal_error (const char *msg) EV_THROW 4139\& fatal_error (const char *msg) EV_NOEXCEPT
4116\& { 4140\& {
4117\& perror (msg); 4141\& perror (msg);
4118\& abort (); 4142\& abort ();
4119\& } 4143\& }
4120\& 4144\&
… …
4518\& ev_vars.h 4542\& ev_vars.h
4519\& ev_wrap.h 4543\& ev_wrap.h
4520\& 4544\&
4521\& ev_win32.c required on win32 platforms only 4545\& ev_win32.c required on win32 platforms only
4522\& 4546\&
4523\& ev_select.c only when select backend is enabled (which is enabled by default) 4547\& ev_select.c only when select backend is enabled
4524\& ev_poll.c only when poll backend is enabled (disabled by default) 4548\& ev_poll.c only when poll backend is enabled
4525\& ev_epoll.c only when the epoll backend is enabled (disabled by default) 4549\& ev_epoll.c only when the epoll backend is enabled
4526\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4550\& ev_kqueue.c only when the kqueue backend is enabled
4527\& ev_port.c only when the solaris port backend is enabled (disabled by default) 4551\& ev_port.c only when the solaris port backend is enabled
4528.Ve 4552.Ve
4529.PP 4553.PP
4530\&\fIev.c\fR includes the backend files directly when enabled, so you only need 4554\&\fIev.c\fR includes the backend files directly when enabled, so you only need
4531to compile this single file. 4555to compile this single file.
4532.PP 4556.PP
… …
5409Libev assumes not only that all watcher pointers have the same internal 5433Libev assumes not only that all watcher pointers have the same internal
5410structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also 5434structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
5411assumes that the same (machine) code can be used to call any watcher 5435assumes that the same (machine) code can be used to call any watcher
5412callback: The watcher callbacks have different type signatures, but libev 5436callback: The watcher callbacks have different type signatures, but libev
5413calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. 5437calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
5438.IP "null pointers and integer zero are represented by 0 bytes" 4
5439.IX Item "null pointers and integer zero are represented by 0 bytes"
5440Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
5441relies on this setting pointers and integers to null.
5414.IP "pointer accesses must be thread-atomic" 4 5442.IP "pointer accesses must be thread-atomic" 4
5415.IX Item "pointer accesses must be thread-atomic" 5443.IX Item "pointer accesses must be thread-atomic"
5416Accessing a pointer value must be atomic, it must both be readable and 5444Accessing a pointer value must be atomic, it must both be readable and
5417writable in one piece \- this is the case on all current architectures. 5445writable in one piece \- this is the case on all current architectures.
5418.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 5446.ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4

Diff Legend

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