--- libev/ev.pod	2008/02/01 13:41:03	1.124
+++ libev/ev.pod	2008/03/08 07:04:56	1.134
@@ -508,6 +508,10 @@
 C<ev_loop_new>. Yes, you have to call this on every allocated event loop
 after fork, and how you do this is entirely your own problem.
 
+=item int ev_is_default_loop (loop)
+
+Returns true when the given loop actually is the default loop, false otherwise.
+
 =item unsigned int ev_loop_count (loop)
 
 Returns the count of loop iterations for the loop, which is identical to
@@ -1154,7 +1158,7 @@
 the timer (because it takes longer than those 10 seconds to do stuff) the
 timer will not fire more than once per event loop iteration.
 
-=item ev_timer_again (loop)
+=item ev_timer_again (loop, ev_timer *)
 
 This will act as if the timer timed out and restart it again if it is
 repeating. The exact semantics are:
@@ -1273,7 +1277,7 @@
 that is, if it is to be run at January 1st 2011 then it will run when the
 system time reaches or surpasses this time.
 
-=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
+=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
 
 In this mode the watcher will always be scheduled to time out at the next
 C<at + N * interval> time (for some integer N, which can also be negative)
@@ -1434,11 +1438,50 @@
 
 =back
 
+=head3 Examples
+
+Example: Try to exit cleanly on SIGINT and SIGTERM.
+
+  static void
+  sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
+  {
+    ev_unloop (loop, EVUNLOOP_ALL);
+  }
+
+  struct ev_signal signal_watcher;
+  ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
+  ev_signal_start (loop, &sigint_cb);
+
 
 =head2 C<ev_child> - watch out for process status changes
 
 Child watchers trigger when your process receives a SIGCHLD in response to
-some child status changes (most typically when a child of yours dies).
+some child status changes (most typically when a child of yours dies). It
+is permissible to install a child watcher I<after> the child has been
+forked (which implies it might have already exited), as long as the event
+loop isn't entered (or is continued from a watcher).
+
+Only the default event loop is capable of handling signals, and therefore
+you can only rgeister child watchers in the default event loop.
+
+=head3 Process Interaction
+
+Libev grabs C<SIGCHLD> as soon as the default event loop is
+initialised. This is necessary to guarantee proper behaviour even if
+the first child watcher is started after the child exits. The occurance
+of C<SIGCHLD> is recorded asynchronously, but child reaping is done
+synchronously as part of the event loop processing. Libev always reaps all
+children, even ones not watched.
+
+=head3 Overriding the Built-In Processing
+
+Libev offers no special support for overriding the built-in child
+processing, but if your application collides with libev's default child
+handler, you can override it easily by installing your own handler for
+C<SIGCHLD> after initialising the default loop, and making sure the
+default loop never gets destroyed. You are encouraged, however, to use an
+event-based approach to child reaping and thus use libev's support for
+that, so other libev users can use C<ev_child> watchers freely.
 
 =head3 Watcher-Specific Functions and Data Members
 
@@ -1474,17 +1517,32 @@
 
 =head3 Examples
 
-Example: Try to exit cleanly on SIGINT and SIGTERM.
+Example: C<fork()> a new process and install a child handler to wait for
+its completion.
+
+  ev_child cw;
 
   static void
-  sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
+  child_cb (EV_P_ struct ev_child *w, int revents)
   {
-    ev_unloop (loop, EVUNLOOP_ALL);
+    ev_child_stop (EV_A_ w);
+    printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
   }
 
-  struct ev_signal signal_watcher;
-  ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
-  ev_signal_start (loop, &sigint_cb);
+  pid_t pid = fork ();
+
+  if (pid < 0)
+    // error
+  else if (pid == 0)
+    {
+      // the forked child executes here
+      exit (1);
+    }
+  else
+    {
+      ev_child_init (&cw, child_cb, pid, 0);
+      ev_child_start (EV_DEFAULT_ &cw);
+    }
 
 
 =head2 C<ev_stat> - did the file attributes just change?
@@ -1574,7 +1632,7 @@
 relative to the attributes at the time the watcher was started (or the
 last change was detected).
 
-=item ev_stat_stat (ev_stat *)
+=item ev_stat_stat (loop, ev_stat *)
 
 Updates the stat buffer immediately with new values. If you change the
 watched path in your callback, you could call this fucntion to avoid
@@ -2080,7 +2138,8 @@
 need elaborate support such as pthreads.
 
 That means that if you want to queue data, you have to provide your own
-queue. And here is how you would implement locking:
+queue. But at least I can tell you would implement locking around your
+queue:
 
 =over 4
 
@@ -2099,7 +2158,7 @@
 
      // no locking etc.
      queue_put (data);
-     ev_async_send (DEFAULT_LOOP, &mysig);
+     ev_async_send (EV_DEFAULT_ &mysig);
    }
 
    static void
@@ -2127,7 +2186,7 @@
 
 The strategy for threads is different, as you cannot (easily) block
 threads but you can easily preempt them, so to queue safely you need to
-emply a traditional mutex lock, such as in this pthread example:
+employ a traditional mutex lock, such as in this pthread example:
 
    static ev_async mysig;
    static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
@@ -2140,7 +2199,7 @@
      queue_put (data);
      pthread_mutex_unlock (&mymutex);
 
-     ev_async_send (DEFAULT_LOOP, &mysig);
+     ev_async_send (EV_DEFAULT_ &mysig);
    }
 
    static void
@@ -2697,11 +2756,13 @@
 =item EV_ATOMIC_T
 
 Libev requires an integer type (suitable for storing C<0> or C<1>) whose
-access is atomic with respect to other threads or signal contexts. No such type
-is easily found using, so you cna provide your own type that you know is safe.
+access is atomic with respect to other threads or signal contexts. No such
+type is easily found in the C language, so you can provide your own type
+that you know is safe for your purposes. It is used both for signal handler "locking"
+as well as for signal and thread safety in C<ev_async> watchers.
 
 In the absense of this define, libev will use C<sig_atomic_t volatile>
-from F<signal.h>, which is usually good enough on most platforms.
+(from F<signal.h>), which is usually good enough on most platforms.
 
 =item EV_H
 
@@ -2912,11 +2973,11 @@
 That means that changing a timer costs less than removing/adding them
 as only the relative motion in the event queue has to be paid for.
 
-=item Starting io/check/prepare/idle/signal/child watchers: O(1)
+=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
 
 These just add the watcher into an array or at the head of a list.
 
-=item Stopping check/prepare/idle watchers: O(1)
+=item Stopping check/prepare/idle/fork/async watchers: O(1)
 
 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
 
@@ -2942,7 +3003,17 @@
 Priorities are implemented by allocating some space for each
 priority. When doing priority-based operations, libev usually has to
 linearly search all the priorities, but starting/stopping and activating
-watchers becomes O(1) w.r.t. prioritiy handling.
+watchers becomes O(1) w.r.t. priority handling.
+
+=item Sending an ev_async: O(1)
+
+=item Processing ev_async_send: O(number_of_async_watchers)
+
+=item Processing signals: O(max_signal_number)
+
+Sending involves a syscall I<iff> there were no other C<ev_async_send>
+calls in the current loop iteration. Checking for async and signal events
+involves iterating over all running async watchers or all signal numbers.
 
 =back