--- libev/ev.pod	2007/12/08 14:12:08	1.74
+++ libev/ev.pod	2007/12/18 13:06:18	1.88
@@ -100,7 +100,9 @@
 the beginning of 1970, details are complicated, don't ask). This type is
 called C<ev_tstamp>, which is what you should use too. It usually aliases
 to the C<double> type in C, and when you need to do any calculations on
-it, you should treat it as such.
+it, you should treat it as some floatingpoint value. Unlike the name
+component C<stamp> might indicate, it is also used for time differences
+throughout libev.
 
 =head1 GLOBAL FUNCTIONS
 
@@ -119,14 +121,17 @@
 
 =item int ev_version_minor ()
 
-You can find out the major and minor version numbers of the library
+You can find out the major and minor ABI version numbers of the library
 you linked against by calling the functions C<ev_version_major> and
 C<ev_version_minor>. If you want, you can compare against the global
 symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
 version of the library your program was compiled against.
 
+These version numbers refer to the ABI version of the library, not the
+release version.
+
 Usually, it's a good idea to terminate if the major versions mismatch,
-as this indicates an incompatible change.  Minor versions are usually
+as this indicates an incompatible change. Minor versions are usually
 compatible to older versions, so a larger minor version alone is usually
 not a problem.
 
@@ -401,9 +406,18 @@
 sense, so e.g. C<ev_is_active> might still return true. It is your
 responsibility to either stop all watchers cleanly yoursef I<before>
 calling this function, or cope with the fact afterwards (which is usually
-the easiest thing, youc na just ignore the watchers and/or C<free ()> them
+the easiest thing, you can just ignore the watchers and/or C<free ()> them
 for example).
 
+Note that certain global state, such as signal state, will not be freed by
+this function, and related watchers (such as signal and child watchers)
+would need to be stopped manually.
+
+In general it is not advisable to call this function except in the
+rare occasion where you really need to free e.g. the signal handling
+pipe fds. If you need dynamically allocated loops it is better to use
+C<ev_loop_new> and C<ev_loop_destroy>).
+
 =item ev_loop_destroy (loop)
 
 Like C<ev_default_destroy>, but destroys an event loop created by an
@@ -488,8 +502,9 @@
 
 Here are the gory details of what C<ev_loop> does:
 
+   - Before the first iteration, call any pending watchers.
    * If there are no active watchers (reference count is zero), return.
-   - Queue prepare watchers and then call all outstanding watchers.
+   - Queue all prepare watchers and then call all outstanding watchers.
    - If we have been forked, recreate the kernel state.
    - Update the kernel state with all outstanding changes.
    - Update the "event loop time".
@@ -909,6 +924,30 @@
 such as poll (fortunately in our Xlib example, Xlib already does this on
 its own, so its quite safe to use).
 
+=head3 The special problem of disappearing file descriptors
+
+Some backends (e.g kqueue, epoll) need to be told about closing a file
+descriptor (either by calling C<close> explicitly or by any other means,
+such as C<dup>). The reason is that you register interest in some file
+descriptor, but when it goes away, the operating system will silently drop
+this interest. If another file descriptor with the same number then is
+registered with libev, there is no efficient way to see that this is, in
+fact, a different file descriptor.
+
+To avoid having to explicitly tell libev about such cases, libev follows
+the following policy:  Each time C<ev_io_set> is being called, libev
+will assume that this is potentially a new file descriptor, otherwise
+it is assumed that the file descriptor stays the same. That means that
+you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
+descriptor even if the file descriptor number itself did not change.
+
+This is how one would do it normally anyway, the important point is that
+the libev application should not optimise around libev but should leave
+optimisations to libev.
+
+
+=head3 Watcher-Specific Functions
+
 =over 4
 
 =item ev_io_init (ev_io *, callback, int fd, int events)
@@ -971,6 +1010,8 @@
 but if multiple timers become ready during the same loop iteration then
 order of execution is undefined.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
@@ -1075,16 +1116,18 @@
 periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
 + 10.>) and then reset your system clock to the last year, then it will
 take a year to trigger the event (unlike an C<ev_timer>, which would trigger
-roughly 10 seconds later and of course not if you reset your system time
-again).
+roughly 10 seconds later).
 
 They can also be used to implement vastly more complex timers, such as
-triggering an event on eahc midnight, local time.
+triggering an event on each midnight, local time or other, complicated,
+rules.
 
 As with timers, the callback is guarenteed to be invoked only when the
 time (C<at>) has been passed, but if multiple periodic timers become ready
 during the same loop iteration then order of execution is undefined.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
@@ -1096,18 +1139,18 @@
 
 =over 4
 
-=item * absolute timer (interval = reschedule_cb = 0)
+=item * absolute timer (at = time, interval = reschedule_cb = 0)
 
 In this configuration the watcher triggers an event at the wallclock time
 C<at> and doesn't repeat. It will not adjust when a time jump occurs,
 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 (interval > 0, reschedule_cb = 0)
+=item * non-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) and then repeat, regardless
-of any time jumps.
+C<at + N * interval> time (for some integer N, which can also be negative)
+and then repeat, regardless of any time jumps.
 
 This can be used to create timers that do not drift with respect to system
 time:
@@ -1123,7 +1166,11 @@
 C<ev_periodic> will try to run the callback in this mode at the next possible
 time where C<time = at (mod interval)>, regardless of any time jumps.
 
-=item * manual reschedule mode (reschedule_cb = callback)
+For numerical stability it is preferable that the C<at> value is near
+C<ev_now ()> (the current time), but there is no range requirement for
+this value.
+
+=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
 
 In this mode the values for C<interval> and C<at> are both being
 ignored. Instead, each time the periodic watcher gets scheduled, the
@@ -1133,7 +1180,7 @@
 NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
 ever, or make any event loop modifications>. If you need to stop it,
 return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
-starting a prepare watcher).
+starting an C<ev_prepare> watcher, which is legal).
 
 Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
 ev_tstamp now)>, e.g.:
@@ -1166,6 +1213,14 @@
 a different time than the last time it was called (e.g. in a crond like
 program when the crontabs have changed).
 
+=item ev_tstamp offset [read-write]
+
+When repeating, this contains the offset value, otherwise this is the
+absolute point in time (the C<at> value passed to C<ev_periodic_set>).
+
+Can be modified any time, but changes only take effect when the periodic
+timer fires or C<ev_periodic_again> is being called.
+
 =item ev_tstamp interval [read-write]
 
 The current interval value. Can be modified any time, but changes only
@@ -1178,6 +1233,11 @@
 switched off. Can be changed any time, but changes only take effect when
 the periodic timer fires or C<ev_periodic_again> is being called.
 
+=item ev_tstamp at [read-only]
+
+When active, contains the absolute time that the watcher is supposed to
+trigger next.
+
 =back
 
 Example: Call a callback every hour, or, more precisely, whenever the
@@ -1228,6 +1288,8 @@
 watcher for a signal is stopped libev will reset the signal handler to
 SIG_DFL (regardless of what it was set to before).
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_signal_init (ev_signal *, callback, int signum)
@@ -1249,6 +1311,8 @@
 Child watchers trigger when your process receives a SIGCHLD in response to
 some child status changes (most typically when a child of yours dies).
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_child_init (ev_child *, callback, int pid)
@@ -1326,6 +1390,8 @@
 usually detected immediately, and if the file exists there will be no
 polling.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
@@ -1417,6 +1483,8 @@
 "pseudo-background processing", or delay processing stuff to after the
 event loop has handled all outstanding events.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_idle_init (ev_signal *, callback)
@@ -1483,6 +1551,18 @@
 loop from blocking if lower-priority coroutines are active, thus mapping
 low-priority coroutines to idle/background tasks).
 
+It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
+too) should not activate ("feed") events into libev. While libev fully
+supports this, they will be called before other C<ev_check> watchers did
+their job. As C<ev_check> watchers are often used to embed other event
+loops those other event loops might be in an unusable state until their
+C<ev_check> watcher ran (always remind yourself to coexist peacefully with
+others).
+
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_prepare_init (ev_prepare *, callback)
@@ -1495,10 +1575,18 @@
 
 =back
 
-Example: To include a library such as adns, you would add IO watchers
-and a timeout watcher in a prepare handler, as required by libadns, and
-in a check watcher, destroy them and call into libadns. What follows is
-pseudo-code only of course:
+There are a number of principal ways to embed other event loops or modules
+into libev. Here are some ideas on how to include libadns into libev
+(there is a Perl module named C<EV::ADNS> that does this, which you could
+use for an actually working example. Another Perl module named C<EV::Glib>
+embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
+into the Glib event loop).
+
+Method 1: Add IO watchers and a timeout watcher in a prepare handler,
+and in a check watcher, destroy them and call into libadns. What follows
+is pseudo-code only of course. This requires you to either use a low
+priority for the check watcher or use C<ev_clear_pending> explicitly, as
+the callbacks for the IO/timeout watchers might not have been called yet.
 
   static ev_io iow [nfd];
   static ev_timer tw;
@@ -1506,11 +1594,6 @@
   static void
   io_cb (ev_loop *loop, ev_io *w, int revents)
   {
-    // set the relevant poll flags
-    // could also call adns_processreadable etc. here
-    struct pollfd *fd = (struct pollfd *)w->data;
-    if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
-    if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
   }
 
   // create io watchers for each fd and a timer before blocking
@@ -1526,7 +1609,7 @@
     ev_timer_init (&tw, 0, timeout * 1e-3);
     ev_timer_start (loop, &tw);
 
-    // create on ev_io per pollfd
+    // create one ev_io per pollfd
     for (int i = 0; i < nfd; ++i)
       {
         ev_io_init (iow + i, io_cb, fds [i].fd,
@@ -1534,7 +1617,6 @@
            | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
 
         fds [i].revents = 0;
-        iow [i].data = fds + i;
         ev_io_start (loop, iow + i);
       }
   }
@@ -1546,11 +1628,80 @@
     ev_timer_stop (loop, &tw);
 
     for (int i = 0; i < nfd; ++i)
-      ev_io_stop (loop, iow + i);
+      {
+        // set the relevant poll flags
+        // could also call adns_processreadable etc. here
+        struct pollfd *fd = fds + i;
+        int revents = ev_clear_pending (iow + i);
+        if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
+        if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
+
+        // now stop the watcher
+        ev_io_stop (loop, iow + i);
+      }
 
     adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
   }
 
+Method 2: This would be just like method 1, but you run C<adns_afterpoll>
+in the prepare watcher and would dispose of the check watcher.
+
+Method 3: If the module to be embedded supports explicit event
+notification (adns does), you can also make use of the actual watcher
+callbacks, and only destroy/create the watchers in the prepare watcher.
+
+  static void
+  timer_cb (EV_P_ ev_timer *w, int revents)
+  {
+    adns_state ads = (adns_state)w->data;
+    update_now (EV_A);
+
+    adns_processtimeouts (ads, &tv_now);
+  }
+
+  static void
+  io_cb (EV_P_ ev_io *w, int revents)
+  {
+    adns_state ads = (adns_state)w->data;
+    update_now (EV_A);
+
+    if (revents & EV_READ ) adns_processreadable  (ads, w->fd, &tv_now);
+    if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
+  }
+
+  // do not ever call adns_afterpoll
+
+Method 4: Do not use a prepare or check watcher because the module you
+want to embed is too inflexible to support it. Instead, youc na override
+their poll function.  The drawback with this solution is that the main
+loop is now no longer controllable by EV. The C<Glib::EV> module does
+this.
+
+  static gint
+  event_poll_func (GPollFD *fds, guint nfds, gint timeout)
+  {
+    int got_events = 0;
+
+    for (n = 0; n < nfds; ++n)
+      // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
+
+    if (timeout >= 0)
+      // create/start timer
+
+    // poll
+    ev_loop (EV_A_ 0);
+
+    // stop timer again
+    if (timeout >= 0)
+      ev_timer_stop (EV_A_ &to);
+
+    // stop io watchers again - their callbacks should have set
+    for (n = 0; n < nfds; ++n)
+      ev_io_stop (EV_A_ iow [n]);
+
+    return got_events;
+  }
+
 
 =head2 C<ev_embed> - when one backend isn't enough...
 
@@ -1622,6 +1773,8 @@
   else
     loop_lo = loop_hi;
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
@@ -1657,6 +1810,8 @@
 C<ev_default_fork> cheats and calls it in the wrong process, the fork
 handlers will be invoked, too, of course.
 
+=head3 Watcher-Specific Functions and Data Members
+
 =over 4
 
 =item ev_fork_init (ev_signal *, callback)
@@ -1846,14 +2001,21 @@
   ev::io iow;
   iow.set <myclass, &myclass::io_cb> (&obj);
 
-=item w->set (void (*function)(watcher &w, int), void *data = 0)
+=item w->set<function> (void *data = 0)
 
 Also sets a callback, but uses a static method or plain function as
 callback. The optional C<data> argument will be stored in the watcher's
 C<data> member and is free for you to use.
 
+The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
+
 See the method-C<set> above for more details.
 
+Example:
+
+  static void io_cb (ev::io &w, int revents) { }
+  iow.set <io_cb> ();
+
 =item w->set (struct ev_loop *)
 
 Associates a different C<struct ev_loop> with this watcher. You can only
@@ -1875,16 +2037,16 @@
 
 Stops the watcher if it is active. Again, no C<loop> argument.
 
-=item w->again ()       C<ev::timer>, C<ev::periodic> only
+=item w->again () (C<ev::timer>, C<ev::periodic> only)
 
 For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
 C<ev_TYPE_again> function.
 
-=item w->sweep ()       C<ev::embed> only
+=item w->sweep () (C<ev::embed> only)
 
 Invokes C<ev_embed_sweep>.
 
-=item w->update ()      C<ev::stat> only
+=item w->update () (C<ev::stat> only)
 
 Invokes C<ev_stat_stat>.
 
@@ -1914,9 +2076,9 @@
 
 =head1 MACRO MAGIC
 
-Libev can be compiled with a variety of options, the most fundemantal is
-C<EV_MULTIPLICITY>. This option determines whether (most) functions and
-callbacks have an initial C<struct ev_loop *> argument.
+Libev can be compiled with a variety of options, the most fundamantal
+of which is C<EV_MULTIPLICITY>. This option determines whether (most)
+functions and callbacks have an initial C<struct ev_loop *> argument.
 
 To make it easier to write programs that cope with either variant, the
 following macros are defined: