--- cvsroot/EV/EV.pm	2007/12/21 13:30:55	1.76
+++ cvsroot/EV/EV.pm	2008/01/28 12:24:05	1.83
@@ -37,7 +37,7 @@
   
   # CHILD/PID STATUS CHANGES
 
-  my $w = EV::child 666, sub {
+  my $w = EV::child 666, 0, sub {
      my ($w, $revents) = @_;
      my $status = $w->rstatus;
   };
@@ -70,7 +70,7 @@
 use strict;
 
 BEGIN {
-   our $VERSION = '2.0';
+   our $VERSION = '3.0';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
@@ -104,7 +104,7 @@
 default loop as this is fastest (perl-wise), best supported by other
 modules (e.g. AnyEvent or Coro) and most portable event loop.
 
-For specific programs you cna create additional event loops dynamically.
+For specific programs you can create additional event loops dynamically.
 
 =over 4
 
@@ -128,6 +128,10 @@
 this fucntion automatically, at some performance loss (refer to the libev
 documentation).
 
+=item $loop = EV::default_loop [$flags]
+
+Return the default loop (which is a singleton object).
+
 =back
 
 
@@ -143,6 +147,20 @@
 
 If this callback throws an exception it will be silently ignored.
 
+=item $flags = EV::supported_backends
+
+=item $flags = EV::recommended_backends
+
+=item $flags = EV::embeddable_backends
+
+Returns the set (see C<EV::BACKEND_*> flags) of backends supported by this
+instance of EV, the set of recommended backends (supposed to be good) for
+this platform and the set of embeddable backends (see EMBED WATCHERS).
+
+=item EV::sleep $seconds
+
+Block the process for the given number of (fractional) seconds.
+
 =item $time = EV::time
 
 Returns the current time in (fractional) seconds since the epoch.
@@ -210,7 +228,7 @@
 
 When an error occurs or either the timeout or I/O watcher triggers, then
 the callback will be called with the received event set (in general
-you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
+you can expect it to be a combination of C<EV::ERROR>, C<EV::READ>,
 C<EV::WRITE> and C<EV::TIMEOUT>).
 
 EV::once doesn't return anything: the watchers stay active till either
@@ -230,6 +248,19 @@
 Feed a signal event into EV. EV will react to this call as if the signal
 specified by C<$signal> had occured.
 
+=item EV::set_io_collect_interval $time
+
+=item $loop->set_io_collect_interval ($time)
+
+=item EV::set_timeout_collect_interval $time
+
+=item $loop->set_timeout_collect_interval ($time)
+
+These advanced functions set the minimum block interval when polling for I/O events and the minimum
+wait interval for timer events. See the libev documentation at
+L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP> for
+a more detailed discussion.
+
 =back
 
 
@@ -241,7 +272,7 @@
 
   my $watcher = EV::io *STDIN, EV::READ, sub {
      my ($watcher, $revents) = @_;
-     warn "yeah, STDIN should not be readable without blocking!\n"
+     warn "yeah, STDIN should now be readable without blocking!\n"
   };
 
 All watchers can be active (waiting for events) or inactive (paused). Only
@@ -335,8 +366,8 @@
 
 =item $revents = $w->clear_pending
 
-If the watcher is pending, this function returns clears its pending status
-and returns its C<$revents> bitset (as if its callback was invoked). If the
+If the watcher is pending, this function clears its pending status and
+returns its C<$revents> bitset (as if its callback was invoked). If the
 watcher isn't pending it does nothing and returns C<0>.
 
 =item $previous_state = $w->keepalive ($bool)
@@ -347,7 +378,7 @@
 call C<EV::loop> once and when it returns you know that all your jobs are
 finished (or they forgot to register some watchers for their task :).
 
-Sometimes, however, this gets in your way, for example when you the module
+Sometimes, however, this gets in your way, for example when the module
 that calls C<EV::loop> (usually the main program) is not the same module
 as a long-living watcher (for example a DNS client module written by
 somebody else even). Then you might want any outstanding requests to be
@@ -615,16 +646,18 @@
 
 =over 4
 
-=item $w = EV::child $pid, $callback
+=item $w = EV::child $pid, $trace, $callback
 
-=item $w = EV::child_ns $pid, $callback
+=item $w = EV::child_ns $pid, $trace, $callback
 
-=item $w = $loop->child ($pid, $callback)
+=item $w = $loop->child ($pid, $trace, $callback)
 
-=item $w = $loop->child_ns ($pid, $callback)
+=item $w = $loop->child_ns ($pid, $trace, $callback)
 
-Call the callback when a status change for pid C<$pid> (or any pid if
-C<$pid> is 0) has been received. More precisely: when the process receives
+Call the callback when a status change for pid C<$pid> (or any pid
+if C<$pid> is 0) has been received (a status change happens when the
+process terminates or is killed, or, when trace is true, additionally when
+it is stopped or continued). More precisely: when the process receives
 a C<SIGCHLD>, EV will fetch the outstanding exit/wait status for all
 changed/zombie children and call the callback.
 
@@ -641,15 +674,13 @@
 
 The C<child_ns> variant doesn't start (activate) the newly created watcher.
 
-=item $w->set ($pid)
+=item $w->set ($pid, $trace)
 
 Reconfigures the watcher, see the constructor above for details. Can be called at
 any time.
 
 =item $current_pid = $w->pid
 
-=item $old_pid = $w->pid ($new_pid)
-
 Returns the previously set process id and optionally set a new one.
 
 =item $exit_status = $w->rstatus
@@ -891,6 +922,54 @@
 
 =back
 
+
+=head3 EMBED WATCHERS - when one backend isn't enough...
+
+This is a rather advanced watcher type that lets you embed one event loop
+into another (currently only 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 the libev documentation at
+L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code_when_one_backend_>
+for more details.
+
+In short, this watcher is most useful on BSD systems without working
+kqueue to still be able to handle a large number of sockets:
+
+  my $socket_loop;
+
+  # check wether we use SELECT or POLL _and_ KQUEUE is supported
+  if (
+    (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
+    && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
+  ) {
+    # use kqueue for sockets
+    $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
+  }
+
+  # use the default loop otherwise
+  $socket_loop ||= EV::default_loop;
+
+=over 4
+
+=item $w = EV::embed $otherloop, $callback
+
+=item $w = EV::embed_ns $otherloop, $callback
+
+=item $w = $loop->embed ($otherloop, $callback)
+
+=item $w = $loop->embed_ns ($otherloop, $callback)
+
+Call the callback when the embedded event loop (C<$otherloop>) has any
+I/O activity. The C<$callback> should alwas be specified as C<undef> in
+this version of EV, which means the embedded event loop will be managed
+automatically.
+
+The C<embed_ns> variant doesn't start (activate) the newly created watcher.
+
+=back
+
 
 =head1 PERL SIGNALS