--- cvsroot/EV/EV.pm	2007/11/23 05:00:44	1.46
+++ cvsroot/EV/EV.pm	2007/11/24 08:42:38	1.50
@@ -64,7 +64,7 @@
    XSLoader::load "EV", $VERSION;
 }
 
-@EV::Io::ISA       =
+@EV::IO::ISA       =
 @EV::Timer::ISA    =
 @EV::Periodic::ISA =
 @EV::Signal::ISA   =
@@ -119,6 +119,29 @@
 When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
 fast as possible.
 
+=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
+
+This function rolls together an I/O and a timer watcher for a single
+one-shot event without the need for managing a watcher object.
+
+If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
+must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
+| EV::WRITE>, indicating the type of I/O event you want to wait for. If
+you do not want to wait for some I/O event, specify C<undef> for
+C<$fh_or_undef> and C<0> for C<$events>).
+
+If timeout is C<undef> or negative, then there will be no
+timeout. Otherwise a EV::timer with this value will be started.
+
+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>,
+C<EV::WRITE> and C<EV::TIMEOUT>).
+
+EV::once doesn't return anything: the watchers stay active till either
+of them triggers, then they will be stopped and freed, and the callback
+invoked.
+
 =back
 
 =head2 WATCHER
@@ -212,12 +235,42 @@
 -2). If the priority is outside this range it will automatically be
 normalised to the nearest valid priority.
 
-The default priority of any newly-created weatcher is 0.
+The default priority of any newly-created watcher is 0.
+
+Note that the priority semantics have not yet been fleshed out and are
+subject to almost certain change.
 
 =item $w->trigger ($revents)
 
 Call the callback *now* with the given event mask.
 
+=item $previous_state = $w->keepalive ($bool)
+
+Normally, C<EV::loop> will return when there are no active watchers
+(which is a "deadlock" because no progress can be made anymore). This is
+convinient because it allows you to start your watchers (and your jobs),
+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
+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
+handled, but you would not want to keep C<EV::loop> from returning just
+because you happen to have this long-running UDP port watcher.
+
+In this case you can clear the keepalive status, which means that even
+though your watcher is active, it won't keep C<EV::loop> from returning.
+
+The initial value for keepalive is true (enabled), and you cna change it
+any time.
+
+Example: Register an IO watcher for some UDP socket but do not keep the
+event loop from running just because of that watcher.
+
+   my $udp_socket = ...
+   my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
+   $udp_watcher->keepalive (0);
 
 =item $w = EV::io $fileno_or_fh, $eventmask, $callback