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

Comparing libev/ev.pod (file contents):
Revision 1.433 by root, Fri May 2 07:05:42 2014 UTC vs.
Revision 1.439 by root, Tue Mar 1 19:19:25 2016 UTC

… …
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 sequence
417without a system call and thus I<very> fast, but my GNU/Linux system also has 417without a system call and thus I<very> fast, but my GNU/Linux system also has
418C<pthread_atfork> which is even faster). 418C<pthread_atfork> which is even faster).
419 419
420The big advantage of this flag is that you can forget about fork (and 420The big advantage of this flag is that you can forget about fork (and
421forget about forgetting to tell libev about forking) when you use this 421forget about forgetting to tell libev about forking, although you still
422flag. 422have to ignore C<SIGPIPE>) when you use this flag.
423 423
424This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 424This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
425environment variable. 425environment variable.
426 426
427=item C<EVFLAG_NOINOTIFY> 427=item C<EVFLAG_NOINOTIFY>
… …
688to reinitialise the kernel state for backends that have one. Despite 688to reinitialise the kernel state for backends that have one. Despite
689the name, you can call it anytime you are allowed to start or stop 689the name, you can call it anytime you are allowed to start or stop
690watchers (except inside an C<ev_prepare> callback), but it makes most 690watchers (except inside an C<ev_prepare> callback), but it makes most
691sense after forking, in the child process. You I<must> call it (or use 691sense after forking, in the child process. You I<must> call it (or use
692C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>. 692C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>.
693
694In addition, if you want to reuse a loop (via this function or
695C<EVFLAG_FORKCHECK>), you I<also> have to ignore C<SIGPIPE>.
693 696
694Again, you I<have> to call it on I<any> loop that you want to re-use after 697Again, you I<have> to call it on I<any> loop that you want to re-use after
695a fork, I<even if you do not plan to use the loop in the parent>. This is 698a fork, I<even if you do not plan to use the loop in the parent>. This is
696because some kernel interfaces *cough* I<kqueue> *cough* do funny things 699because some kernel interfaces *cough* I<kqueue> *cough* do funny things
697during fork. 700during fork.
… …
2029 2032
2030The relative timeouts are calculated relative to the C<ev_now ()> 2033The relative timeouts are calculated relative to the C<ev_now ()>
2031time. This is usually the right thing as this timestamp refers to the time 2034time. This is usually the right thing as this timestamp refers to the time
2032of the event triggering whatever timeout you are modifying/starting. If 2035of the event triggering whatever timeout you are modifying/starting. If
2033you suspect event processing to be delayed and you I<need> to base the 2036you suspect event processing to be delayed and you I<need> to base the
2034timeout on the current time, use something like this to adjust for this: 2037timeout on the current time, use something like the following to adjust
2038for it:
2035 2039
2036 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2040 ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.);
2037 2041
2038If the event loop is suspended for a long time, you can also force an 2042If the event loop is suspended for a long time, you can also force an
2039update of the time returned by C<ev_now ()> by calling C<ev_now_update 2043update of the time returned by C<ev_now ()> by calling C<ev_now_update
2040()>. 2044()>, although that will push the event time of all outstanding events
2045further into the future.
2041 2046
2042=head3 The special problem of unsynchronised clocks 2047=head3 The special problem of unsynchronised clocks
2043 2048
2044Modern systems have a variety of clocks - libev itself uses the normal 2049Modern systems have a variety of clocks - libev itself uses the normal
2045"wall clock" clock and, if available, the monotonic clock (to avoid time 2050"wall clock" clock and, if available, the monotonic clock (to avoid time
… …
2204Periodic watchers are also timers of a kind, but they are very versatile 2209Periodic watchers are also timers of a kind, but they are very versatile
2205(and unfortunately a bit complex). 2210(and unfortunately a bit complex).
2206 2211
2207Unlike C<ev_timer>, periodic watchers are not based on real time (or 2212Unlike C<ev_timer>, periodic watchers are not based on real time (or
2208relative time, the physical time that passes) but on wall clock time 2213relative time, the physical time that passes) but on wall clock time
2209(absolute time, the thing you can read on your calender or clock). The 2214(absolute time, the thing you can read on your calendar or clock). The
2210difference is that wall clock time can run faster or slower than real 2215difference is that wall clock time can run faster or slower than real
2211time, and time jumps are not uncommon (e.g. when you adjust your 2216time, and time jumps are not uncommon (e.g. when you adjust your
2212wrist-watch). 2217wrist-watch).
2213 2218
2214You can tell a periodic watcher to trigger after some specific point 2219You can tell a periodic watcher to trigger after some specific point
… …
3898To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two 3903To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
3899files, F<my_ev.h> and F<my_ev.c> that include the respective libev files: 3904files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3900 3905
3901 // my_ev.h 3906 // my_ev.h
3902 #define EV_CB_DECLARE(type) struct my_coro *cb; 3907 #define EV_CB_DECLARE(type) struct my_coro *cb;
3903 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb); 3908 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
3904 #include "../libev/ev.h" 3909 #include "../libev/ev.h"
3905 3910
3906 // my_ev.c 3911 // my_ev.c
3907 #define EV_H "my_ev.h" 3912 #define EV_H "my_ev.h"
3908 #include "../libev/ev.c" 3913 #include "../libev/ev.c"
… …
5295structure (guaranteed by POSIX but not by ISO C for example), but it also 5300structure (guaranteed by POSIX but not by ISO C for example), but it also
5296assumes that the same (machine) code can be used to call any watcher 5301assumes that the same (machine) code can be used to call any watcher
5297callback: The watcher callbacks have different type signatures, but libev 5302callback: The watcher callbacks have different type signatures, but libev
5298calls them using an C<ev_watcher *> internally. 5303calls them using an C<ev_watcher *> internally.
5299 5304
5305=item null pointers and integer zero are represented by 0 bytes
5306
5307Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
5308relies on this setting pointers and integers to null.
5309
5300=item pointer accesses must be thread-atomic 5310=item pointer accesses must be thread-atomic
5301 5311
5302Accessing a pointer value must be atomic, it must both be readable and 5312Accessing a pointer value must be atomic, it must both be readable and
5303writable in one piece - this is the case on all current architectures. 5313writable in one piece - this is the case on all current architectures.
5304 5314

Diff Legend

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