--- libev/ev.pod	2007/12/21 05:10:01	1.95
+++ libev/ev.pod	2007/12/23 03:50:10	1.105
@@ -6,7 +6,7 @@
 
   #include <ev.h>
 
-=head1 EXAMPLE PROGRAM
+=head2 EXAMPLE PROGRAM
 
   #include <ev.h>
 
@@ -67,7 +67,7 @@
 details of the event, and then hand it over to libev by I<starting> the
 watcher.
 
-=head1 FEATURES
+=head2 FEATURES
 
 Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
 BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
@@ -84,7 +84,7 @@
 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
 for example).
 
-=head1 CONVENTIONS
+=head2 CONVENTIONS
 
 Libev is very configurable. In this manual the default configuration will
 be described, which supports multiple event loops. For more info about
@@ -93,7 +93,7 @@
 loops, then all functions taking an initial argument of name C<loop>
 (which is always of type C<struct ev_loop *>) will not have this argument.
 
-=head1 TIME REPRESENTATION
+=head2 TIME REPRESENTATION
 
 Libev represents time as a single floating point number, representing the
 (fractional) number of seconds since the (POSIX) epoch (somewhere near
@@ -117,6 +117,12 @@
 C<ev_now> function is usually faster and also often returns the timestamp
 you actually want to know.
 
+=item ev_sleep (ev_tstamp interval)
+
+Sleep for the given interval: The current thread will be blocked until
+either it is interrupted or the given time interval has passed. Basically
+this is a subsecond-resolution C<sleep ()>.
+
 =item int ev_version_major ()
 
 =item int ev_version_minor ()
@@ -302,15 +308,24 @@
 This is your standard select(2) backend. Not I<completely> standard, as
 libev tries to roll its own fd_set with no limits on the number of fds,
 but if that fails, expect a fairly low limit on the number of fds when
-using this backend. It doesn't scale too well (O(highest_fd)), but its usually
-the fastest backend for a low number of fds.
+using this backend. It doesn't scale too well (O(highest_fd)), but its
+usually the fastest backend for a low number of (low-numbered :) fds.
+
+To get good performance out of this backend you need a high amount of
+parallelity (most of the file descriptors should be busy). If you are
+writing a server, you should C<accept ()> in a loop to accept as many
+connections as possible during one iteration. You might also want to have
+a look at C<ev_set_io_collect_interval ()> to increase the amount of
+readyness notifications you get per iteration.
 
 =item C<EVBACKEND_POLL>    (value 2, poll backend, available everywhere except on windows)
 
-And this is your standard poll(2) backend. It's more complicated than
-select, but handles sparse fds better and has no artificial limit on the
-number of fds you can use (except it will slow down considerably with a
-lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
+And this is your standard poll(2) backend. It's more complicated
+than select, but handles sparse fds better and has no artificial
+limit on the number of fds you can use (except it will slow down
+considerably with a lot of inactive fds). It scales similarly to select,
+i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
+performance tips.
 
 =item C<EVBACKEND_EPOLL>   (value 4, Linux)
 
@@ -319,8 +334,8 @@
 like O(total_fds) where n is the total number of fds (or the highest fd),
 epoll scales either O(1) or O(active_fds). The epoll design has a number
 of shortcomings, such as silently dropping events in some hard-to-detect
-cases and rewuiring a syscall per fd change, no fork support and bad
-support for dup:
+cases and rewiring a syscall per fd change, no fork support and bad
+support for dup.
 
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a syscall per such incident
@@ -332,27 +347,49 @@
 need to use non-blocking I/O or other means to avoid blocking when no data
 (or space) is available.
 
+Best performance from this backend is achieved by not unregistering all
+watchers for a file descriptor until it has been closed, if possible, i.e.
+keep at least one watcher active per fd at all times.
+
+While nominally embeddeble in other event loops, this feature is broken in
+all kernel versions tested so far.
+
 =item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
 
 Kqueue deserves special mention, as at the time of this writing, it
-was broken on I<all> BSDs (usually it doesn't work with anything but
-sockets and pipes, except on Darwin, where of course it's completely
-useless. On NetBSD, it seems to work for all the FD types I tested, so it
-is used by default there). For this reason it's not being "autodetected"
+was broken on all BSDs except NetBSD (usually it doesn't work reliably
+with anything but sockets and pipes, except on Darwin, where of course
+it's completely useless). For this reason it's not being "autodetected"
 unless you explicitly specify it explicitly in the flags (i.e. using
 C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
 system like NetBSD.
 
+You still can embed kqueue into a normal poll or select backend and use it
+only for sockets (after having made sure that sockets work with kqueue on
+the target platform). See C<ev_embed> watchers for more info.
+
 It scales in the same way as the epoll backend, but the interface to the
-kernel is more efficient (which says nothing about its actual speed,
-of course). While stopping, setting and starting an I/O watcher does
-never cause an extra syscall as with epoll, it still adds up to two event
-changes per incident, support for C<fork ()> is very bad and it drops fds
-silently in similarly hard-to-detetc cases.
+kernel is more efficient (which says nothing about its actual speed, of
+course). While stopping, setting and starting an I/O watcher does never
+cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
+two event changes per incident, support for C<fork ()> is very bad and it
+drops fds silently in similarly hard-to-detect cases.
+
+This backend usually performs well under most conditions.
+
+While nominally embeddable in other event loops, this doesn't work
+everywhere, so you might need to test for this. And since it is broken
+almost everywhere, you should only use it when you have a lot of sockets
+(for which it usually works), by embedding it into another event loop
+(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
+sockets.
 
 =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
 
-This is not implemented yet (and might never be).
+This is not implemented yet (and might never be, unless you send me an
+implementation). According to reports, C</dev/poll> only supports sockets
+and is not embeddable, which would limit the usefulness of this backend
+immensely.
 
 =item C<EVBACKEND_PORT>    (value 32, Solaris 10)
 
@@ -363,12 +400,19 @@
 notifications, so you need to use non-blocking I/O or other means to avoid
 blocking when no data (or space) is available.
 
+While this backend scales well, it requires one system call per active
+file descriptor per loop iteration. For small and medium numbers of file
+descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
+might perform better.
+
 =item C<EVBACKEND_ALL>
 
 Try all backends (even potentially broken ones that wouldn't be tried
 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
 C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
 
+It is definitely not recommended to use this flag.
+
 =back
 
 If one or more of these are ored into the flags value, then only these
@@ -571,6 +615,42 @@
   ev_ref (loop);
   ev_signal_stop (loop, &exitsig);
 
+=item ev_set_io_collect_interval (loop, ev_tstamp interval)
+
+=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
+
+These advanced functions influence the time that libev will spend waiting
+for events. Both are by default C<0>, meaning that libev will try to
+invoke timer/periodic callbacks and I/O callbacks with minimum latency.
+
+Setting these to a higher value (the C<interval> I<must> be >= C<0>)
+allows libev to delay invocation of I/O and timer/periodic callbacks to
+increase efficiency of loop iterations.
+
+The background is that sometimes your program runs just fast enough to
+handle one (or very few) event(s) per loop iteration. While this makes
+the program responsive, it also wastes a lot of CPU time to poll for new
+events, especially with backends like C<select ()> which have a high
+overhead for the actual polling but can deliver many events at once.
+
+By setting a higher I<io collect interval> you allow libev to spend more
+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.
+
+Likewise, by setting a higher I<timeout collect interval> you allow libev
+to spend more time collecting timeouts, at the expense of increased
+latency (the watcher callback will be called later). C<ev_io> watchers
+will not be affected. Setting this to a non-null value will not introduce
+any overhead in libev.
+
+Many (busy) programs can usually benefit by setting the io collect
+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 approsaches the timing granularity of most systems.
+
 =back
 
 
@@ -954,12 +1034,12 @@
 =head3 The special problem of dup'ed file descriptors
 
 Some backends (e.g. epoll), cannot register events for file descriptors,
-but only events for the underlying file descriptions. That menas when you
+but only events for the underlying file descriptions. That means when you
 have C<dup ()>'ed file descriptors and register events for them, only one
 file descriptor might actually receive events.
 
-There is no workaorund possible except not registering events
-for potentially C<dup ()>'ed file descriptors or to resort to
+There is no workaround possible except not registering events
+for potentially C<dup ()>'ed file descriptors, or to resort to
 C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
 
 =head3 The special problem of fork
@@ -1583,11 +1663,11 @@
 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).
+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
+(non-libev) 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
 
@@ -1736,7 +1816,7 @@
 This is a rather advanced watcher type that lets you embed one event loop
 into another (currently only C<ev_io> events are supported in the embedded
 loop, other types of watchers might be handled in a delayed or incorrect
-fashion and must not be used). (See portability notes, below).
+fashion and must not be used).
 
 There are primarily two reasons you would want that: work around bugs and
 prioritise I/O.
@@ -1801,22 +1881,6 @@
   else
     loop_lo = loop_hi;
 
-=head2 Portability notes
-
-Kqueue is nominally embeddable, but this is broken on all BSDs that I
-tried, in various ways. Usually the embedded event loop will simply never
-receive events, sometimes it will only trigger a few times, sometimes in a
-loop. Epoll is also nominally embeddable, but many Linux kernel versions
-will always eport the epoll fd as ready, even when no events are pending.
-
-While libev allows embedding these backends (they are contained in
-C<ev_embeddable_backends ()>), take extreme care that it will actually
-work.
-
-When in doubt, create a dynamic event loop forced to use sockets (this
-usually works) and possibly another thread and a pipe or so to report to
-your main event loop.
-
 =head3 Watcher-Specific Functions and Data Members
 
 =over 4
@@ -2299,6 +2363,11 @@
 (CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
 note about libraries in the description of C<EV_USE_MONOTONIC>, though.
 
+=item EV_USE_NANOSLEEP
+
+If defined to be C<1>, libev will assume that C<nanosleep ()> is available
+and will use it for delays. Otherwise it will use C<select ()>.
+
 =item EV_USE_SELECT
 
 If undefined or defined to be C<1>, libev will compile in support for the
@@ -2459,7 +2528,7 @@
 
 =item EV_INOTIFY_HASHSIZE
 
-C<ev_staz> watchers use a small hash table to distribute workload by
+C<ev_stat> watchers use a small hash table to distribute workload by
 inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
 usually more than enough. If you need to manage thousands of C<ev_stat>
 watchers you might want to increase this value (I<must> be a power of