--- cvsroot/EV/EV.pm	2007/12/21 05:30:25	1.74
+++ cvsroot/EV/EV.pm	2007/12/22 16:37:07	1.79
@@ -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,16 @@
 
 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 $time = EV::time
 
 Returns the current time in (fractional) seconds since the epoch.
@@ -210,7 +224,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 +244,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 +268,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 +362,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 +374,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
@@ -386,7 +413,7 @@
 
 =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
 
-=item $w = $loop->io 8$fileno_or_fh, $eventmask, $callback)
+=item $w = $loop->io ($fileno_or_fh, $eventmask, $callback)
 
 =item $w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
 
@@ -793,7 +820,7 @@
 
 =item $w = $loop->prepare ($callback)
 
-=item $w = $loop->prepare_ns 8$callback)
+=item $w = $loop->prepare_ns ($callback)
 
 Call the callback just before the process would block. You can still
 create/modify any watchers at this point.
@@ -892,6 +919,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
 
 While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour
@@ -908,8 +983,8 @@
 
    my $async_check = EV::check sub { };
 
-This ensures that perl shortly gets into control for a short time, and
-also ensures slower overall operation.
+This ensures that perl gets into control for a short time to handle any
+pending signals, and also ensures (slightly) slower overall operation.
 
 =head1 THREADS