--- cvsroot/EV/EV.pm	2009/12/31 06:59:47	1.125
+++ cvsroot/EV/EV.pm	2010/10/21 15:13:42	1.129
@@ -53,6 +53,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
 
+=head1 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 L<AnyEvent> instead,
+specifically the simplified API described in L<AE>.
+
+When used with EV as backend, the L<AE> API is as fast as the native L<EV>
+API, but your programs/modules will still run with many other event loops.
+
 =head1 DESCRIPTION
 
 This module provides an interface to libev
@@ -70,6 +79,37 @@
 and still be faster than with any other event loop currently supported in
 Perl.
 
+=head2 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.
+
 =head2 MODULE EXPORTS
 
 This module does not export any symbols.
@@ -81,7 +121,7 @@
 use common::sense;
 
 BEGIN {
-   our $VERSION = '3.9';
+   our $VERSION = '4.00';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
@@ -301,7 +341,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 C<EV::ERROR>, C<EV::READ>,
-C<EV::WRITE> and C<EV::TIMEOUT>).
+C<EV::WRITE> and C<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 the callback
@@ -368,8 +408,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).
+(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 C<_ns> in
@@ -944,7 +983,7 @@
 Call the callback just after the process wakes up again (after it 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 out):
@@ -989,6 +1028,16 @@
 
 The C<check_ns> variant doesn't start (activate) the newly created watcher.
 
+=item EV::CHECK constant issues
+
+Like all other watcher types, there is a bitmask constant for use in
+C<$revents> and other places. The C<EV::CHECK> is special as it has
+the same name as the C<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 I<inlined>, i.e. runtime calls will not work. That means
+that as long as you always C<use EV> and then C<EV::CHECK> you are on the
+safe side.
+
 =back