[ViewVC] Diff of: cvs/libev/ev.3

Comparing libev/ev.3 (file contents):
Revision 1.101 by root, Fri Dec 27 06:01:21 2013 UTC vs.
Revision 1.106 by root, Wed Nov 16 17:39:52 2016 UTC

-.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
+.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2013-12-27" "libev-4.15" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2016-11-16" "libev-4.23" "libev - high performance full featured event loop"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence
 without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has
 \&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster).
 .Sp
 The big advantage of this flag is that you can forget about fork (and
-forget about forgetting to tell libev about forking) when you use this
+forget about forgetting to tell libev about forking, although you still
-flag.
+have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag.
 .Sp
 This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
 environment variable.
 .ie n .IP """EVFLAG_NOINOTIFY""" 4
 .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
 except in the rare occasion where you really need to free its resources.
 If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR
 and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
 .IP "ev_loop_fork (loop)" 4
 .IX Item "ev_loop_fork (loop)"
-This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to
+This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations
-reinitialise the kernel state for backends that have one. Despite the
+to reinitialise the kernel state for backends that have one. Despite
-name, you can call it anytime, but it makes most sense after forking, in
+the name, you can call it anytime you are allowed to start or stop
-the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the
+watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
-child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
+sense after forking, in the child process. You \fImust\fR call it (or use
+\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
+.Sp
+In addition, if you want to reuse a loop (via this function or
+\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR.
 .Sp
 Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
 a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
 because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
 during fork.
 .PP
 The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
 time. This is usually the right thing as this timestamp refers to the time
 of the event triggering whatever timeout you are modifying/starting. If
 you suspect event processing to be delayed and you \fIneed\fR to base the
-timeout on the current time, use something like this to adjust for this:
+timeout on the current time, use something like the following to adjust
+for it:
 .PP
 .Vb 1
-\&   ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.);
+\&   ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.);
 .Ve
 .PP
 If the event loop is suspended for a long time, you can also force an
 update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
-()\*(C'\fR.
+()\*(C'\fR, although that will push the event time of all outstanding events
+further into the future.
 .PP
 \fIThe special problem of unsynchronised clocks\fR
 .IX Subsection "The special problem of unsynchronised clocks"
 .PP
 Modern systems have a variety of clocks \- libev itself uses the normal
 Periodic watchers are also timers of a kind, but they are very versatile
 (and unfortunately a bit complex).
 .PP
 Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or
 relative time, the physical time that passes) but on wall clock time
-(absolute time, the thing you can read on your calender or clock). The
+(absolute time, the thing you can read on your calendar or clock). The
 difference is that wall clock time can run faster or slower than real
 time, and time jumps are not uncommon (e.g. when you adjust your
 wrist-watch).
 .PP
 You can tell a periodic watcher to trigger after some specific point
 .IX Subsection "ev_prepare and ev_check - customise your event loop!"
 Prepare and check watchers are often (but not always) used in pairs:
 prepare watchers get invoked before the process blocks and check watchers
 afterwards.
 .PP
-You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter
+You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the
-the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR
+current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or
-watchers. Other loops than the current one are fine, however. The
+\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine,
-rationale behind this is that you do not need to check for recursion in
+however. The rationale behind this is that you do not need to check
-those watchers, i.e. the sequence will always be \f(CW\*(C`ev_prepare\*(C'\fR, blocking,
+for recursion in those watchers, i.e. the sequence will always be
-\&\f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each kind they will always be
+\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each
-called in pairs bracketing the blocking call.
+kind they will always be called in pairs bracketing the blocking call.
 .PP
 Their main purpose is to integrate other event mechanisms into libev and
 their use is somewhat advanced. They could be used, for example, to track
 variable changes, implement your own watchers, integrate net-snmp or a
 coroutine library and lots more. They are also occasionally useful if
 .PP
 .Vb 3
 \&   struct ev_loop *loop_hi = ev_default_init (0);
 \&   struct ev_loop *loop_lo = 0;
 \&   ev_embed embed;
 \&
 \&   // see if there is a chance of getting one that works
 \&   // (remember that a flags value of 0 means autodetection)
 \&   loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
 \&     ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
 \&     : 0;
 .PP
 .Vb 3
 \&   struct ev_loop *loop = ev_default_init (0);
 \&   struct ev_loop *loop_socket = 0;
 \&   ev_embed embed;
 \&
 \&   if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
 \&     if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
 \&       {
 \&         ev_embed_init (&embed, 0, loop_socket);
 \&         ev_embed_start (loop, &embed);
 of course.
 .PP
 \fIThe special problem of life after fork \- how is it possible?\fR
 .IX Subsection "The special problem of life after fork - how is it possible?"
 .PP
-Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
+Most uses of \f(CW\*(C`fork ()\*(C'\fR consist of forking, then some simple calls to set
 up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This
 sequence should be handled by libev without any problems.
 .PP
 This changes when the application actually wants to do event handling
 in the child, or both parent in child, in effect \*(L"continuing\*(R" after the
 files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
 .PP
 .Vb 4
 \&   // my_ev.h
 \&   #define EV_CB_DECLARE(type)   struct my_coro *cb;
-\&   #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb);
+\&   #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
 \&   #include "../libev/ev.h"
 \&
 \&   // my_ev.c
 \&   #define EV_H "my_ev.h"
 \&   #include "../libev/ev.c"
 \&     void operator() (ev::io &w, int revents)
 \&     {
 \&       ...
 \&     }
 \&   }
 \&
 \&   myfunctor f;
 \&
 \&   ev::io w;
 \&   w.set (&f);
 .Ve
 Libev assumes not only that all watcher pointers have the same internal
 structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also
 assumes that the same (machine) code can be used to call any watcher
 callback: The watcher callbacks have different type signatures, but libev
 calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally.
+.IP "null pointers and integer zero are represented by 0 bytes" 4
+.IX Item "null pointers and integer zero are represented by 0 bytes"
+Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and
+relies on this setting pointers and integers to null.
 .IP "pointer accesses must be thread-atomic" 4
 .IX Item "pointer accesses must be thread-atomic"
 Accessing a pointer value must be atomic, it must both be readable and
 writable in one piece \- this is the case on all current architectures.
 .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.101 by root, Fri Dec 27 06:01:21 2013 UTC vs. Revision 1.106 by root, Wed Nov 16 17:39:52 2016 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.101 by root, Fri Dec 27 06:01:21 2013 UTC vs.
Revision 1.106 by root, Wed Nov 16 17:39:52 2016 UTC