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

Comparing libev/ev.pod (file contents):
Revision 1.438 by root, Tue Jan 12 05:52:44 2016 UTC vs.
Revision 1.444 by root, Mon Oct 29 00:00:22 2018 UTC

… …
411make libev check for a fork in each iteration by enabling this flag. 411make libev check for a fork in each iteration by enabling this flag.
412 412
413This works by calling C<getpid ()> on every iteration of the loop, 413This works by calling C<getpid ()> on every iteration of the loop,
414and thus this might slow down your event loop if you do a lot of loop 414and thus this might slow down your event loop if you do a lot of loop
415iterations and little real work, but is usually not noticeable (on my 415iterations and little real work, but is usually not noticeable (on my
416GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 416GNU/Linux system for example, C<getpid> is actually a simple 5-insn
417without a system call and thus I<very> fast, but my GNU/Linux system also has 417sequence without a system call and thus I<very> fast, but my GNU/Linux
418C<pthread_atfork> which is even faster). 418system also has C<pthread_atfork> which is even faster). (Update: glibc
419versions 2.25 apparently removed the C<getpid> optimisation again).
419 420
420The big advantage of this flag is that you can forget about fork (and 421The big advantage of this flag is that you can forget about fork (and
421forget about forgetting to tell libev about forking, although you still 422forget about forgetting to tell libev about forking, although you still
422have to ignore C<SIGPIPE>) when you use this flag. 423have to ignore C<SIGPIPE>) when you use this flag.
423 424
… …
2113 2114
2114=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 2115=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
2115 2116
2116=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 2117=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
2117 2118
2118Configure the timer to trigger after C<after> seconds. If C<repeat> 2119Configure the timer to trigger after C<after> seconds (fractional and
2119is C<0.>, then it will automatically be stopped once the timeout is 2120negative values are supported). If C<repeat> is C<0.>, then it will
2120reached. If it is positive, then the timer will automatically be 2121automatically be stopped once the timeout is reached. If it is positive,
2121configured to trigger again C<repeat> seconds later, again, and again, 2122then the timer will automatically be configured to trigger again C<repeat>
2122until stopped manually. 2123seconds later, again, and again, until stopped manually.
2123 2124
2124The timer itself will do a best-effort at avoiding drift, that is, if 2125The timer itself will do a best-effort at avoiding drift, that is, if
2125you configure a timer to trigger every 10 seconds, then it will normally 2126you configure a timer to trigger every 10 seconds, then it will normally
2126trigger at exactly 10 second intervals. If, however, your program cannot 2127trigger at exactly 10 second intervals. If, however, your program cannot
2127keep up with the timer (because it takes longer than those 10 seconds to 2128keep up with the timer (because it takes longer than those 10 seconds to
… …
2224C<ev_timer>, which would still trigger roughly 10 seconds after starting 2225C<ev_timer>, which would still trigger roughly 10 seconds after starting
2225it, as it uses a relative timeout). 2226it, as it uses a relative timeout).
2226 2227
2227C<ev_periodic> watchers can also be used to implement vastly more complex 2228C<ev_periodic> watchers can also be used to implement vastly more complex
2228timers, such as triggering an event on each "midnight, local time", or 2229timers, such as triggering an event on each "midnight, local time", or
2229other complicated rules. This cannot be done with C<ev_timer> watchers, as 2230other complicated rules. This cannot easily be done with C<ev_timer>
2230those cannot react to time jumps. 2231watchers, as those cannot react to time jumps.
2231 2232
2232As with timers, the callback is guaranteed to be invoked only when the 2233As with timers, the callback is guaranteed to be invoked only when the
2233point in time where it is supposed to trigger has passed. If multiple 2234point in time where it is supposed to trigger has passed. If multiple
2234timers become ready during the same loop iteration then the ones with 2235timers become ready during the same loop iteration then the ones with
2235earlier time-out values are invoked before ones with later time-out values 2236earlier time-out values are invoked before ones with later time-out values
… …
2321 2322
2322NOTE: I<< This callback must always return a time that is higher than or 2323NOTE: I<< This callback must always return a time that is higher than or
2323equal to the passed C<now> value >>. 2324equal to the passed C<now> value >>.
2324 2325
2325This can be used to create very complex timers, such as a timer that 2326This can be used to create very complex timers, such as a timer that
2326triggers on "next midnight, local time". To do this, you would calculate the 2327triggers on "next midnight, local time". To do this, you would calculate
2327next midnight after C<now> and return the timestamp value for this. How 2328the next midnight after C<now> and return the timestamp value for
2328you do this is, again, up to you (but it is not trivial, which is the main 2329this. Here is a (completely untested, no error checking) example on how to
2329reason I omitted it as an example). 2330do this:
2331
2332 #include <time.h>
2333
2334 static ev_tstamp
2335 my_rescheduler (ev_periodic *w, ev_tstamp now)
2336 {
2337 time_t tnow = (time_t)now;
2338 struct tm tm;
2339 localtime_r (&tnow, &tm);
2340
2341 tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2342 ++tm.tm_mday; // midnight next day
2343
2344 return mktime (&tm);
2345 }
2346
2347Note: this code might run into trouble on days that have more then two
2348midnights (beginning and end).
2330 2349
2331=back 2350=back
2332 2351
2333=item ev_periodic_again (loop, ev_periodic *) 2352=item ev_periodic_again (loop, ev_periodic *)
2334 2353
… …
3517 3536
3518There are some other functions of possible interest. Described. Here. Now. 3537There are some other functions of possible interest. Described. Here. Now.
3519 3538
3520=over 4 3539=over 4
3521 3540
3522=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 3541=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)
3523 3542
3524This function combines a simple timer and an I/O watcher, calls your 3543This function combines a simple timer and an I/O watcher, calls your
3525callback on whichever event happens first and automatically stops both 3544callback on whichever event happens first and automatically stops both
3526watchers. This is useful if you want to wait for a single event on an fd 3545watchers. This is useful if you want to wait for a single event on an fd
3527or timeout without having to allocate/configure/start/stop/free one or 3546or timeout without having to allocate/configure/start/stop/free one or
… …
4386 ev_vars.h 4405 ev_vars.h
4387 ev_wrap.h 4406 ev_wrap.h
4388 4407
4389 ev_win32.c required on win32 platforms only 4408 ev_win32.c required on win32 platforms only
4390 4409
4391 ev_select.c only when select backend is enabled (which is enabled by default) 4410 ev_select.c only when select backend is enabled
4392 ev_poll.c only when poll backend is enabled (disabled by default) 4411 ev_poll.c only when poll backend is enabled
4393 ev_epoll.c only when the epoll backend is enabled (disabled by default) 4412 ev_epoll.c only when the epoll backend is enabled
4394 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4413 ev_kqueue.c only when the kqueue backend is enabled
4395 ev_port.c only when the solaris port backend is enabled (disabled by default) 4414 ev_port.c only when the solaris port backend is enabled
4396 4415
4397F<ev.c> includes the backend files directly when enabled, so you only need 4416F<ev.c> includes the backend files directly when enabled, so you only need
4398to compile this single file. 4417to compile this single file.
4399 4418
4400=head3 LIBEVENT COMPATIBILITY API 4419=head3 LIBEVENT COMPATIBILITY API
… …
5300structure (guaranteed by POSIX but not by ISO C for example), but it also 5319structure (guaranteed by POSIX but not by ISO C for example), but it also
5301assumes that the same (machine) code can be used to call any watcher 5320assumes that the same (machine) code can be used to call any watcher
5302callback: The watcher callbacks have different type signatures, but libev 5321callback: The watcher callbacks have different type signatures, but libev
5303calls them using an C<ev_watcher *> internally. 5322calls them using an C<ev_watcher *> internally.
5304 5323
5324=item null pointers and integer zero are represented by 0 bytes
5325
5326Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
5327relies on this setting pointers and integers to null.
5328
5305=item pointer accesses must be thread-atomic 5329=item pointer accesses must be thread-atomic
5306 5330
5307Accessing a pointer value must be atomic, it must both be readable and 5331Accessing a pointer value must be atomic, it must both be readable and
5308writable in one piece - this is the case on all current architectures. 5332writable in one piece - this is the case on all current architectures.
5309 5333

Diff Legend

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