--- cvsroot/EV/EV.pm	2007/11/23 13:09:02	1.48
+++ cvsroot/EV/EV.pm	2007/11/24 16:20:30	1.52
@@ -50,7 +50,11 @@
 =head1 DESCRIPTION
 
 This module provides an interface to libev
-(L<http://software.schmorp.de/pkg/libev.html>).
+(L<http://software.schmorp.de/pkg/libev.html>). While the documentation
+below is comprehensive, one might also consult the documentation of libev
+itself (L<http://cvs.schmorp.de/libev/ev.html>) for more subtle details on
+watcher semantics or some discussion on the available backends, or how to
+force a specific backend with C<LIBEV_FLAGS>.
 
 =cut
 
@@ -59,12 +63,12 @@
 use strict;
 
 BEGIN {
-   our $VERSION = '1.2';
+   our $VERSION = '1.3';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
 
-@EV::Io::ISA       =
+@EV::IO::ISA       =
 @EV::Timer::ISA    =
 @EV::Periodic::ISA =
 @EV::Signal::ISA   =
@@ -235,12 +239,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