--- EV/README	2007/12/05 14:06:50	1.15
+++ EV/README	2007/12/07 18:11:23	1.16
@@ -58,7 +58,8 @@
     below is comprehensive, one might also consult the documentation of
     libev itself (<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 "LIBEV_FLAGS".
+    backends, or how to force a specific backend with "LIBEV_FLAGS", or just
+    about in any case because it has much more detailed information.
 
 BASIC INTERFACE
     $EV::DIED
@@ -141,7 +142,7 @@
     Each watcher type has its associated bit in revents, so you can use the
     same callback for multiple watchers. The event mask is named after the
     type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
-    EV::periodic sets EV::PERIODIC and so on, with the exception of IO
+    EV::periodic sets EV::PERIODIC and so on, with the exception of I/O
     events (which can set both EV::READ and EV::WRITE bits), and EV::timer
     (which uses EV::TIMEOUT).
 
@@ -169,8 +170,8 @@
     $w->stop
         Stop a watcher if it is active. Also clear any pending events
         (events that have been received but that didn't yet result in a
-        callback invocation), regardless of wether the watcher was active or
-        not.
+        callback invocation), regardless of whether the watcher was active
+        or not.
 
     $bool = $w->is_active
         Returns true if the watcher is active, false otherwise.
@@ -229,7 +230,7 @@
         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
+        Example: Register an I/O watcher for some UDP socket but do not keep
         the event loop from running just because of that watcher.
 
            my $udp_socket = ...
@@ -239,7 +240,7 @@
   WATCHER TYPES
     Each of the following subsections describes a single watcher type.
 
-   IO WATCHERS - is this file descriptor readable or writable?
+   I/O WATCHERS - is this file descriptor readable or writable?
     $w = EV::io $fileno_or_fh, $eventmask, $callback
     $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
         As long as the returned watcher object is alive, call the $callback
@@ -526,12 +527,25 @@
    IDLE WATCHERS - when you've got nothing better to do...
     $w = EV::idle $callback
     $w = EV::idle_ns $callback
-        Call the callback when there are no pending io, timer/periodic,
-        signal or child events, i.e. when the process is idle.
+        Call the callback when there are no other pending watchers of the
+        same or higher priority (excluding check, prepare and other idle
+        watchers of the same or lower priority, of course). They are called
+        idle watchers because when the watcher is the highest priority
+        pending event in the process, the process is considered to be idle
+        at that priority.
+
+        If you want a watcher that is only ever called when *no* other
+        events are outstanding you have to set the priority to "EV::MINPRI".
 
         The process will not block as long as any idle watchers are active,
         and they will be called repeatedly until stopped.
 
+        For example, if you have idle watchers at priority 0 and 1, and an
+        I/O watcher at priority 0, then the idle watcher at priority 1 and
+        the I/O watcher will always run when ready. Only when the idle
+        watcher at priority 1 is stopped and the I/O watcher at priority 0
+        is not pending with the 0-priority idle watcher be invoked.
+
         The "idle_ns" variant doesn't start (activate) the newly created
         watcher.
 
@@ -569,7 +583,7 @@
               # make the dispatcher handle any outstanding stuff
               ... not shown
 
-              # create an IO watcher for each and every socket
+              # create an I/O watcher for each and every socket
               @snmp_watcher = (
                  (map { EV::io $_, EV::READ, sub { } }
                      keys %{ $dispatcher->{_descriptors} }),
@@ -613,6 +627,24 @@
         The "fork_ns" variant doesn't start (activate) the newly created
         watcher.
 
+PERL SIGNALS
+    While Perl signal handling (%SIG) is not affected by EV, the behaviour
+    with EV is as the same as any other C library: Perl-signals will only be
+    handled when Perl runs, which means your signal handler might be invoked
+    only the next time an event callback is invoked.
+
+    The solution is to use EV signal watchers (see "EV::signal"), which will
+    ensure proper operations with regards to other event watchers.
+
+    If you cannot do this for whatever reason, you can also force a watcher
+    to be called on every event loop iteration by installing a "EV::check"
+    watcher:
+
+       my $async_check = EV::check sub { };
+
+    This ensures that perl shortly gets into control for a short time, and
+    also ensures slower overall operation.
+
 THREADS
     Threads are not supported by this module in any way. Perl pseudo-threads
     is evil stuff and must die. As soon as Perl gains real threads I will