--- EV/EV.pm	2007/11/24 08:28:10	1.49
+++ EV/EV.pm	2007/11/24 08:42:38	1.50
@@ -235,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