--- libev/ev.pod	2011/01/11 01:42:47	1.356
+++ libev/ev.pod	2011/02/20 02:56:23	1.367
@@ -60,7 +60,7 @@
      // now wait for events to arrive
      ev_run (loop, 0);
 
-     // unloop was called, so exit
+     // break was called, so exit
      return 0;
    }
 
@@ -444,6 +444,9 @@
 want to handle signals only in specific threads and want to avoid libev
 unblocking the signals.
 
+It's also required by POSIX in a threaded program, as libev calls
+C<sigprocmask>, whose behaviour is officially unspecified.
+
 This flag's behaviour will become the default in future versions of libev.
 
 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
@@ -867,7 +870,7 @@
    ... queue jobs here, make sure they register event watchers as long
    ... as they still have work to do (even an idle watcher will do..)
    ev_run (my_loop, 0);
-   ... jobs done or somebody called unloop. yeah!
+   ... jobs done or somebody called break. yeah!
 
 =item ev_break (loop, how)
 
@@ -1359,70 +1362,8 @@
 
 =back
 
-=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
-
-Each watcher has, by default, a member C<void *data> that you can change
-and read at any time: libev will completely ignore it. This can be used
-to associate arbitrary data with your watcher. If you need more data and
-don't want to allocate memory and store a pointer to it in that data
-member, you can also "subclass" the watcher type and provide your own
-data:
-
-   struct my_io
-   {
-     ev_io io;
-     int otherfd;
-     void *somedata;
-     struct whatever *mostinteresting;
-   };
-
-   ...
-   struct my_io w;
-   ev_io_init (&w.io, my_cb, fd, EV_READ);
-
-And since your callback will be called with a pointer to the watcher, you
-can cast it back to your own type:
-
-   static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
-   {
-     struct my_io *w = (struct my_io *)w_;
-     ...
-   }
-
-More interesting and less C-conformant ways of casting your callback type
-instead have been omitted.
-
-Another common scenario is to use some data structure with multiple
-embedded watchers:
-
-   struct my_biggy
-   {
-     int some_data;
-     ev_timer t1;
-     ev_timer t2;
-   }
-
-In this case getting the pointer to C<my_biggy> is a bit more
-complicated: Either you store the address of your C<my_biggy> struct
-in the C<data> member of the watcher (for woozies), or you need to use
-some pointer arithmetic using C<offsetof> inside your watchers (for real
-programmers):
-
-   #include <stddef.h>
-
-   static void
-   t1_cb (EV_P_ ev_timer *w, int revents)
-   {
-     struct my_biggy big = (struct my_biggy *)
-       (((char *)w) - offsetof (struct my_biggy, t1));
-   }
-
-   static void
-   t2_cb (EV_P_ ev_timer *w, int revents)
-   {
-     struct my_biggy big = (struct my_biggy *)
-       (((char *)w) - offsetof (struct my_biggy, t2));
-   }
+See also the L<ASSOCIATING CUSTOM DATA WITH A WATCHER> and L<BUILDING YOUR
+OWN COMPOSITE WATCHERS> idioms.
 
 =head2 WATCHER STATES
 
@@ -1439,8 +1380,10 @@
 initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
 C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
 
-In this state it is simply some block of memory that is suitable for use
-in an event loop. It can be moved around, freed, reused etc. at will.
+In this state it is simply some block of memory that is suitable for
+use in an event loop. It can be moved around, freed, reused etc. at
+will - as long as you either keep the memory contents intact, or call
+C<ev_TYPE_init> again.
 
 =item started/running/active
 
@@ -1478,8 +1421,9 @@
 freeing it is often a good idea.
 
 While stopped (and not pending) the watcher is essentially in the
-initialised state, that is it can be reused, moved, modified in any way
-you wish.
+initialised state, that is, it can be reused, moved, modified in any way
+you wish (but when you trash the memory block, you need to C<ev_TYPE_init>
+it again).
 
 =back
 
@@ -1682,8 +1626,8 @@
 
 Another way to view it is that in the case of sockets, pipes, character
 devices and so on, there is another party (the sender) that delivers data
-on it's own, but in the case of files, there is no such thing: the disk
-will not send data on it's own, simply because it doesn't know what you
+on its own, but in the case of files, there is no such thing: the disk
+will not send data on its own, simply because it doesn't know what you
 wish to read - you would first have to request some data.
 
 Since files are typically not-so-well supported by advanced notification
@@ -2209,9 +2153,12 @@
 C<ev_periodic> will try to run the callback in this mode at the next possible
 time where C<time = offset (mod interval)>, regardless of any time jumps.
 
-For numerical stability it is preferable that the C<offset> value is near
-C<ev_now ()> (the current time), but there is no range requirement for
-this value, and in fact is often specified as zero.
+The C<interval> I<MUST> be positive, and for numerical stability, the
+interval value should be higher than C<1/8192> (which is around 100
+microseconds) and C<offset> should be higher than C<0> and should have
+at most a similar magnitude as the current time (say, within a factor of
+ten). Typical values for offset are, in fact, C<0> or something between
+C<0> and C<interval>, which is also the recommended range.
 
 Note also that there is an upper limit to how often a timer can fire (CPU
 speed for example), so if C<interval> is very small then timing stability
@@ -2364,7 +2311,8 @@
 Both the signal mask (C<sigprocmask>) and the signal disposition
 (C<sigaction>) are unspecified after starting a signal watcher (and after
 stopping it again), that is, libev might or might not block the signal,
-and might or might not set or restore the installed signal handler.
+and might or might not set or restore the installed signal handler (but
+see C<EVFLAG_NOSIGMASK>).
 
 While this does not matter for the signal disposition (libev never
 sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
@@ -3245,7 +3193,7 @@
 
 =head2 C<ev_async> - how to wake up an event loop
 
-In general, you cannot use an C<ev_run> from multiple threads or other
+In general, you cannot use an C<ev_loop> from multiple threads or other
 asynchronous sources such as signal handlers (as opposed to multiple event
 loops - those are of course safe to use in different threads).
 
@@ -3365,10 +3313,12 @@
 =item ev_async_send (loop, ev_async *)
 
 Sends/signals/activates the given C<ev_async> watcher, that is, feeds
-an C<EV_ASYNC> event on the watcher into the event loop. Unlike
-C<ev_feed_event>, this call is safe to do from other threads, signal or
-similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
-section below on what exactly this means).
+an C<EV_ASYNC> event on the watcher into the event loop, and instantly
+returns.
+
+Unlike C<ev_feed_event>, this call is safe to do from other threads,
+signal or similar contexts (see the discussion of C<EV_ATOMIC_T> in the
+embedding section below on what exactly this means).
 
 Note that, as with other watchers in libev, multiple events might get
 compressed into a single callback invocation (another way to look at this
@@ -3458,6 +3408,74 @@
 obvious. Note that examples are sprinkled over the whole manual, and this
 section only contains stuff that wouldn't fit anywhere else.
 
+=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
+
+Each watcher has, by default, a C<void *data> member that you can read
+or modify at any time: libev will completely ignore it. This can be used
+to associate arbitrary data with your watcher. If you need more data and
+don't want to allocate memory separately and store a pointer to it in that
+data member, you can also "subclass" the watcher type and provide your own
+data:
+
+   struct my_io
+   {
+     ev_io io;
+     int otherfd;
+     void *somedata;
+     struct whatever *mostinteresting;
+   };
+
+   ...
+   struct my_io w;
+   ev_io_init (&w.io, my_cb, fd, EV_READ);
+
+And since your callback will be called with a pointer to the watcher, you
+can cast it back to your own type:
+
+   static void my_cb (struct ev_loop *loop, ev_io *w_, int revents)
+   {
+     struct my_io *w = (struct my_io *)w_;
+     ...
+   }
+
+More interesting and less C-conformant ways of casting your callback
+function type instead have been omitted.
+
+=head2 BUILDING YOUR OWN COMPOSITE WATCHERS
+
+Another common scenario is to use some data structure with multiple
+embedded watchers, in effect creating your own watcher that combines
+multiple libev event sources into one "super-watcher":
+
+   struct my_biggy
+   {
+     int some_data;
+     ev_timer t1;
+     ev_timer t2;
+   }
+
+In this case getting the pointer to C<my_biggy> is a bit more
+complicated: Either you store the address of your C<my_biggy> struct in
+the C<data> member of the watcher (for woozies or C++ coders), or you need
+to use some pointer arithmetic using C<offsetof> inside your watchers (for
+real programmers):
+
+   #include <stddef.h>
+
+   static void
+   t1_cb (EV_P_ ev_timer *w, int revents)
+   {
+     struct my_biggy big = (struct my_biggy *)
+       (((char *)w) - offsetof (struct my_biggy, t1));
+   }
+
+   static void
+   t2_cb (EV_P_ ev_timer *w, int revents)
+   {
+     struct my_biggy big = (struct my_biggy *)
+       (((char *)w) - offsetof (struct my_biggy, t2));
+   }
+
 =head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
 
 Often (especially in GUI toolkits) there are places where you have
@@ -3500,7 +3518,7 @@
 =head2 THREAD LOCKING EXAMPLE
 
 Here is a fictitious example of how to run an event loop in a different
-thread than where callbacks are being invoked and watchers are
+thread from where callbacks are being invoked and watchers are
 created/added/removed.
 
 For a real-world example, see the C<EV::Loop::Async> perl module,
@@ -3536,7 +3554,7 @@
       ev_set_invoke_pending_cb (EV_A_ l_invoke);
       ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
 
-      // then create the thread running ev_loop
+      // then create the thread running ev_run
       pthread_create (&u->tid, 0, l_run, EV_A);
    }
 
@@ -3635,6 +3653,64 @@
 about the newly added timer. By waking up the loop it will pick up any new
 watchers in the next event loop iteration.
 
+=head2 THREADS, COROUTINES, CONTINUATIONS, QUEUES... INSTEAD OF CALLBACKS
+
+While the overhead of a callback that e.g. schedules a thread is small, it
+is still an overhead. If you embed libev, and your main usage is with some
+kind of threads or coroutines, you might want to customise libev so that
+doesn't need callbacks anymore.
+
+Imagine you have coroutines that you can switch to using a function
+C<switch_to (coro)>, that libev runs in a coroutine called C<libev_coro>
+and that due to some magic, the currently active coroutine is stored in a
+global called C<current_coro>. Then you can build your own "wait for libev
+event" primitive by changing C<EV_CB_DECLARE> and C<EV_CB_INVOKE> (note
+the differing C<;> conventions):
+
+   #define EV_CB_DECLARE(type)   struct my_coro *cb;
+   #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
+
+That means instead of having a C callback function, you store the
+coroutine to switch to in each watcher, and instead of having libev call
+your callback, you instead have it switch to that coroutine.
+
+A coroutine might now wait for an event with a function called
+C<wait_for_event>. (the watcher needs to be started, as always, but it doesn't
+matter when, or whether the watcher is active or not when this function is
+called):
+
+   void
+   wait_for_event (ev_watcher *w)
+   {
+     ev_cb_set (w) = current_coro;
+     switch_to (libev_coro);
+   }
+
+That basically suspends the coroutine inside C<wait_for_event> and
+continues the libev coroutine, which, when appropriate, switches back to
+this or any other coroutine. I am sure if you sue this your own :)
+
+You can do similar tricks if you have, say, threads with an event queue -
+instead of storing a coroutine, you store the queue object and instead of
+switching to a coroutine, you push the watcher onto the queue and notify
+any waiters.
+
+To embed libev, see L<EMBEDDING>, but in short, it's easiest to create two
+files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
+
+   // my_ev.h
+   #define EV_CB_DECLARE(type)   struct my_coro *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"
+
+And then use F<my_ev.h> when you would normally use F<ev.h>, and compile
+F<my_ev.c> into your project. When properly specifying include paths, you
+can even use F<ev.h> as header file name directly.
+
 
 =head1 LIBEVENT EMULATION
 
@@ -4133,6 +4209,15 @@
 In standalone mode, libev will still try to automatically deduce the
 configuration, but has to be more conservative.
 
+=item EV_USE_FLOOR
+
+If defined to be C<1>, libev will use the C<floor ()> function for its
+periodic reschedule calculations, otherwise libev will fall back on a
+portable (slower) implementation. If you enable this, you usually have to
+link against libm or something equivalent. Enabling this when the C<floor>
+function is not available will fail, so the safe default is to not enable
+this.
+
 =item EV_USE_MONOTONIC
 
 If defined to be C<1>, libev will try to detect the availability of the
@@ -5153,7 +5238,7 @@
 =item wall-clock time
 
 The time and date as shown on clocks. Unlike real time, it can actually
-be wrong and jump forwards and backwards, e.g. when the you adjust your
+be wrong and jump forwards and backwards, e.g. when you adjust your
 clock.
 
 =item watcher
@@ -5166,5 +5251,5 @@
 =head1 AUTHOR
 
 Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
-Magnusson and Emanuele Giaquinta.
+Magnusson and Emanuele Giaquinta, and minor corrections by many others.