--- libev/ev.pod	2009/06/29 04:41:34	1.244
+++ libev/ev.pod	2009/07/10 00:36:21	1.251
@@ -623,6 +623,18 @@
 "ticks" the number of loop iterations), as it roughly corresponds with
 C<ev_prepare> and C<ev_check> calls.
 
+=item unsigned int ev_loop_depth (loop)
+
+Returns the number of times C<ev_loop> was entered minus the number of
+times C<ev_loop> was exited, in other words, the recursion depth.
+
+Outside C<ev_loop>, this number is zero. In a callback, this number is
+C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
+in which case it is higher.
+
+Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
+etc.), doesn't count as exit.
+
 =item unsigned int ev_backend (loop)
 
 Returns one of the C<EVBACKEND_*> flags indicating the event backend in
@@ -813,7 +825,9 @@
 time collecting I/O events, so you can handle more events per iteration,
 at the cost of increasing latency. Timeouts (both C<ev_periodic> and
 C<ev_timer>) will be not affected. Setting this to a non-null value will
-introduce an additional C<ev_sleep ()> call into most loop iterations.
+introduce an additional C<ev_sleep ()> call into most loop iterations. The
+sleep time ensures that libev will not poll for I/O events more often then
+once per this interval, on average.
 
 Likewise, by setting a higher I<timeout collect interval> you allow libev
 to spend more time collecting timeouts, at the expense of increased
@@ -825,7 +839,11 @@
 interval to a value near C<0.1> or so, which is often enough for
 interactive servers (of course not for games), likewise for timeouts. It
 usually doesn't make much sense to set it to a lower value than C<0.01>,
-as this approaches the timing granularity of most systems.
+as this approaches the timing granularity of most systems. Note that if
+you do transactions with the outside world and you can't increase the
+parallelity, then this setting will limit your transaction rate (if you
+need to poll once per transaction and the I/O collect interval is 0.01,
+then you can't do more than 100 transations per second).
 
 Setting the I<timeout collect interval> can improve the opportunity for
 saving power, as the program will "bundle" timer callback invocations that
@@ -834,6 +852,12 @@
 reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
 they fire on, say, one-second boundaries only.
 
+Example: we only need 0.1s timeout granularity, and we wish not to poll
+more often than 100 times per second:
+
+   ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
+   ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
+
 =item ev_loop_verify (loop)
 
 This function only does something when C<EV_VERIFY> support has been
@@ -1470,8 +1494,8 @@
 passed (not I<at>, so on systems with very low-resolution clocks this
 might introduce a small delay). If multiple timers become ready during the
 same loop iteration then the ones with earlier time-out values are invoked
-before ones with later time-out values (but this is no longer true when a
-callback calls C<ev_loop> recursively).
+before ones of the same priority with later time-out values (but this is
+no longer true when a callback calls C<ev_loop> recursively).
 
 =head3 Be smart about timeouts
 
@@ -2010,6 +2034,10 @@
 Only the default event loop is capable of handling signals, and therefore
 you can only register child watchers in the default event loop.
 
+Due to some design glitches inside libev, child watchers will always be
+handled at maximum priority (their priority is set to C<EV_MAXPRI> by
+libev)
+
 =head3 Process Interaction
 
 Libev grabs C<SIGCHLD> as soon as the default event loop is
@@ -3645,9 +3673,18 @@
 =item EV_MINIMAL
 
 If you need to shave off some kilobytes of code at the expense of some
-speed, define this symbol to C<1>. Currently this is used to override some
-inlining decisions, saves roughly 30% code size on amd64. It also selects a
-much smaller 2-heap for timer management over the default 4-heap.
+speed (but with the full API), define this symbol to C<1>. Currently this
+is used to override some inlining decisions, saves roughly 30% code size
+on amd64. It also selects a much smaller 2-heap for timer management over
+the default 4-heap.
+
+You can save even more by disabling watcher types you do not need and
+setting C<EV_MAXPRI> == C<EV_MINPRI>.
+
+Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
+provide a bare-bones event library. See C<ev.h> for details on what parts
+of the API are still available, and do not complain if this subset changes
+over time.
 
 =item EV_PID_HASHSIZE
 
@@ -4067,7 +4104,9 @@
 The type C<double> is used to represent timestamps. It is required to
 have at least 51 bits of mantissa (and 9 bits of exponent), which is good
 enough for at least into the year 4000. This requirement is fulfilled by
-implementations implementing IEEE 754 (basically all existing ones).
+implementations implementing IEEE 754, which is basically all existing
+ones. With IEEE 754 doubles, you get microsecond accuracy until at least
+2200.
 
 =back