--- cvsroot/EV/README	2009/12/31 06:59:47	1.35
+++ cvsroot/EV/README	2010/10/25 11:30:45	1.38
@@ -52,6 +52,15 @@
        EV::loop EV::LOOP_ONESHOT;  # block until at least one event could be handled
        EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
 
+BEFORE YOU START USING THIS MODULE
+    If you only need timer, I/O, signal, child and idle watchers and not the
+    advanced functionality of this module, consider using AnyEvent instead,
+    specifically the simplified API described in AE.
+
+    When used with EV as backend, the AE API is as fast as the native EV
+    API, but your programs/modules will still run with many other event
+    loops.
+
 DESCRIPTION
     This module provides an interface to libev
     (<http://software.schmorp.de/pkg/libev.html>). While the documentation
@@ -68,6 +77,36 @@
     and still be faster than with any other event loop currently supported
     in Perl.
 
+  PORTING FROM EV 3.X to 4.X
+    EV version 4 introduces a number of incompatible changes summarised
+    here. According to the depreciation strategy used by libev, there is a
+    compatibility layer in place so programs should continue to run
+    unchanged (the XS interface lacks this layer, so programs using that one
+    need to be updated).
+
+    This compatibility layer will be switched off in some future release.
+
+    All changes relevant to Perl are renames of symbols, functions and
+    methods:
+
+      EV::loop          => EV::run
+      EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
+      EV::LOOP_ONESHOT  => EV::RUN_ONCE
+
+      EV::unloop        => EV::break
+      EV::UNLOOP_CANCEL => EV::BREAK_CANCEL
+      EV::UNLOOP_ONE    => EV::BREAK_ONE
+      EV::UNLOOP_ALL    => EV::BREAK_ALL
+
+      EV::TIMEOUT       => EV::TIMER
+
+      EV::loop_count    => EV::iteration
+      EV::loop_depth    => EV::depth
+      EV::loop_verify   => EV::verify
+
+    The loop object methods corresponding to the functions above have been
+    similarly renamed.
+
   MODULE EXPORTS
     This module does not export any symbols.
 
@@ -237,7 +276,7 @@
         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 "EV::ERROR",
-        "EV::READ", "EV::WRITE" and "EV::TIMEOUT").
+        "EV::READ", "EV::WRITE" and "EV::TIMER").
 
         EV::once doesn't return anything: the watchers stay active till
         either of them triggers, then they will be stopped and freed, and
@@ -292,8 +331,7 @@
     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 I/O
-    events (which can set both EV::READ and EV::WRITE bits), and EV::timer
-    (which uses EV::TIMEOUT).
+    events (which can set both EV::READ and EV::WRITE bits).
 
     In the rare case where one wants to create a watcher but not start it at
     the same time, each constructor has a variant with a trailing "_ns" in
@@ -760,7 +798,7 @@
         has gathered events), but before any other callbacks have been
         invoked.
 
-        This is used to integrate other event-based software into the EV
+        This can be used to integrate other event-based software into the EV
         mainloop: You register a prepare callback and in there, you create
         io and timer watchers as required by the other software. Here is a
         real-world example of integrating Net::SNMP (with some details left
@@ -807,6 +845,15 @@
         The "check_ns" variant doesn't start (activate) the newly created
         watcher.
 
+    EV::CHECK constant issues
+        Like all other watcher types, there is a bitmask constant for use in
+        $revents and other places. The "EV::CHECK" is special as it has the
+        same name as the "CHECK" sub called by Perl. This doesn't cause big
+        issues on newer perls (beginning with 5.8.9), but it means thatthe
+        constant must be *inlined*, i.e. runtime calls will not work. That
+        means that as long as you always "use EV" and then "EV::CHECK" you
+        are on the safe side.
+
    FORK WATCHERS - the audacity to resume the event loop after a fork
     Fork watchers are called when a "fork ()" was detected. The invocation
     is done before the event loop blocks next and before "check" watchers
@@ -917,10 +964,11 @@
     course.
 
 SEE ALSO
-    EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event
-    loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
-    with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop
-    agnostic and portable event driven programming.
+    EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous
+    DNS), Glib::EV (makes Glib/Gtk2 use EV as event loop), EV::Glib (embed
+    Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV
+    (asynchronous SNMP), AnyEvent for event-loop agnostic and portable event
+    driven programming.
 
 AUTHOR
        Marc Lehmann <schmorp@schmorp.de>