--- EV-Loop-Async/Async.pm	2009/07/14 15:09:44	1.3
+++ EV-Loop-Async/Async.pm	2009/07/17 02:52:22	1.4
@@ -135,6 +135,14 @@
       # the loop will not be locked, however.
    }
 
+Example: embed the default EV::Async::Loop loop into the default L<EV>
+loop (note that it could be any other event loop as well).
+
+   my $async_w = EV::io
+                    $EV::Loop::Async::LOOP->interrupt->pipe_fileno,
+                    EV::READ,
+                    sub { };
+
 =item $loop = new EV::Loop::Async $flags, [Async-Interrupt-Arguments...]
 
 This constructor:
@@ -153,6 +161,25 @@
 
 The resulting loop will be running and unlocked when it is returned.
 
+Example: create a new loop, block it's interrupt object and embed
+it into the foreground L<AnyEvent> event loop. This basically runs the
+C<EV::Loop::Async> loop in a synchronous way inside another loop.
+
+   my $loop  = new EV::Loop::Async 0;
+   my $async = $loop->interrupt;
+
+   $async->block;
+
+   my $async_w = AnyEvent->io (
+      fh => $async->pipe_fileno,
+      poll => "r",
+      cb => sub {
+         # temporarily unblock to handle events
+         $async->unblock;
+         $async->block;
+      },
+   );
+
 =cut
 
 sub new {
@@ -219,6 +246,27 @@
 Calls C<lock> immediately, and C<unlock> automatically whent he current
 scope is left.
 
+=item $loop->set_max_foreground_loops ($max_loops)
+
+The background loop will immediately stop polling for new events after it
+has collected at least one new event, regardless of how long it then takes
+to actually handle them.
+
+When Perl finally handles the events, there could be many more ready
+file descriptors. To improve latency and performance, you can ask
+C<EV::Loop::Async> to loop an additional number of times in the foreground
+after invoking the callbacks, effectively doing the polling in the
+foreground.
+
+The default is C<0>, meaning thatno foreground polling will be done. A
+value of C<1> means that, after handling the pending events, it will call
+C<< $loop->loop (EV::LOOP_NONBLOCK) >> and handle the resulting events, if
+any. A value of C<2> means that this will be iterated twice.
+
+When a foreground event poll does not yield any new events, then no
+further iterations will be made, so this is only a I<maximum> value of
+additional loop runs.
+
 =back
 
 =head1 SEE ALSO