--- cvsroot/EV/EV.pm 2009/07/14 20:31:21 1.118 +++ cvsroot/EV/EV.pm 2010/12/05 11:45:22 1.131 @@ -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 instead, +specifically the simplified API described in L. + +When used with EV as backend, the L API is as fast as the native L +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.7'; + our $VERSION = '4.01'; 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, C, -C and C). +C and C). 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 @@ -333,6 +373,18 @@ L (locally installed as F) 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 @@ -356,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 @@ -446,7 +497,7 @@ Normally, C 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 once and when it returns you know that all your jobs are finished (or they forgot to register some watchers for their task :). @@ -688,9 +739,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 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 @@ -924,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): @@ -969,6 +1028,16 @@ The C 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 is special as it has +the same name as the C 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, i.e. runtime calls will not work. That means +that as long as you always C and then C you are on the +safe side. + =back @@ -1121,9 +1190,10 @@ =head1 SEE ALSO -L (asynchronous DNS), L (makes Glib/Gtk2 use EV as -event loop), L (embed Glib into EV), L (efficient -coroutines with EV), L (asynchronous SNMP), L for +L - MakeMaker interface to XS API, L +(asynchronous DNS), L (makes Glib/Gtk2 use EV as event +loop), L (embed Glib into EV), L (efficient thread +integration), L (asynchronous SNMP), L for event-loop agnostic and portable event driven programming. =head1 AUTHOR