--- cvsroot/EV/EV.pm	2009/03/14 16:24:27	1.113
+++ cvsroot/EV/EV.pm	2010/10/21 02:46:59	1.128
@@ -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
@@ -78,11 +87,10 @@
 
 package EV;
 
-no warnings;
-use strict;
+use common::sense;
 
 BEGIN {
-   our $VERSION = '3.53';
+   our $VERSION = '4.00';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
@@ -204,6 +212,48 @@
 is the time that (relative) timers are based on, and referring to it is
 usually faster then calling EV::time.
 
+=item EV::now_update
+
+=item $loop->now_update
+
+Establishes the current time by querying the kernel, updating the time
+returned by C<EV::now> in the progress. This is a costly operation and
+is usually done automatically within C<EV::loop>.
+
+This function is rarely useful, but when some event callback runs for a
+very long time without entering the event loop, updating libev's idea of
+the current time is a good idea.
+
+=item EV::suspend
+
+=item $loop->suspend
+
+=item EV::resume
+
+=item $loop->resume
+
+These two functions suspend and resume a loop, for use when the loop is
+not used for a while and timeouts should not be processed.
+
+A typical use case would be an interactive program such as a game:  When
+the user presses C<^Z> to suspend the game and resumes it an hour later it
+would be best to handle timeouts as if no time had actually passed while
+the program was suspended. This can be achieved by calling C<suspend>
+in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
+C<resume> directly afterwards to resume timer processing.
+
+Effectively, all C<timer> watchers will be delayed by the time spend
+between C<suspend> and C<resume>, and all C<periodic> watchers
+will be rescheduled (that is, they will lose any events that would have
+occured while suspended).
+
+After calling C<suspend> you B<must not> call I<any> function on the given
+loop other than C<resume>, and you B<must not> call C<resume>
+without a previous call to C<suspend>.
+
+Calling C<suspend>/C<resume> has the side effect of updating the event
+loop time (see C<now_update>).
+
 =item $backend = EV::backend
 
 =item $backend = $loop->backend
@@ -260,7 +310,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
@@ -292,6 +342,18 @@
 L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP>
 (locally installed as F<EV::libev>) for a more detailed discussion.
 
+=item $count = EV::pending_count
+
+=item $count = $loop->pending_count
+
+Returns the number of currently pending watchers.
+
+=item EV::invoke_pending
+
+=item $loop->invoke_pending
+
+Invoke all currently pending watchers.
+
 =back
 
 
@@ -315,8 +377,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
@@ -405,7 +466,7 @@
 
 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),
+convenient 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 :).
 
@@ -647,9 +708,17 @@
 
 =item $w = EV::signal_ns $signal, $callback
 
+=item $w = $loop->signal ($signal, $callback)
+
+=item $w = $loop->signal_ns ($signal, $callback)
+
 Call the callback when $signal is received (the signal can be specified by
 number or by name, just as with C<kill> or C<%SIG>).
 
+Only one event loop can grab a given signal - attempting to grab the same
+signal from two EV loops will crash the program immediately or cause data
+corruption.
+
 EV will grab the signal for the process (the kernel only allows one
 component to receive a signal at a time) when you start a signal watcher,
 and removes it again when you stop it. Perl does the same when you
@@ -883,7 +952,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):
@@ -928,6 +997,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
 
 
@@ -1004,9 +1083,9 @@
 
 =head3 ASYNC WATCHERS - how to wake up another event loop
 
-Async watchers are provided by EV, but have little use in perl directly, as perl
-neither supports threads nor direct access to signal handlers or other
-contexts where they could be of value.
+Async watchers are provided by EV, but have little use in perl directly,
+as perl neither supports threads running in parallel nor direct access to
+signal handlers or other contexts where they could be of value.
 
 It is, however, possible to use them from the XS level.
 
@@ -1044,11 +1123,11 @@
 This ensures that perl gets into control for a short time to handle any
 pending signals, and also ensures (slightly) slower overall operation.
 
-=head1 THREADS
+=head1 ITHREADS
 
-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 work
-on thread support for it.
+Ithreads are not supported by this module in any way. Perl pseudo-threads
+is evil stuff and must die. Real threads as provided by Coro are fully
+supported (and enhanced support is available via L<Coro::EV>).
 
 =head1 FORK