--- cvsroot/EV/EV.pm 2007/12/22 16:48:33 1.80 +++ cvsroot/EV/EV.pm 2008/05/22 02:44:57 1.96 @@ -37,7 +37,7 @@ # CHILD/PID STATUS CHANGES - my $w = EV::child 666, sub { + my $w = EV::child 666, 0, sub { my ($w, $revents) = @_; my $status = $w->rstatus; }; @@ -58,10 +58,16 @@ This module provides an interface to libev (L). While the documentation below is comprehensive, one might also consult the documentation of libev -itself (L) for more subtle details on -watcher semantics or some discussion on the available backends, or how to -force a specific backend with C, or just about in any case -because it has much more detailed information. +itself (L) for more +subtle details on watcher semantics or some discussion on the available +backends, or how to force a specific backend with C, or just +about in any case because it has much more detailed information. + +This module is very fast and scalable. It is actually so fast that you +can use it through the L module, stay portable to other event +loops (if you don't rely on any watcher types not available through it) +and still be faster than with any other event loop currently supported in +Perl. =cut @@ -70,7 +76,7 @@ use strict; BEGIN { - our $VERSION = '2.0'; + our $VERSION = '3.41'; use XSLoader; XSLoader::load "EV", $VERSION; } @@ -86,6 +92,7 @@ @EV::Check::ISA = @EV::Embed::ISA = @EV::Fork::ISA = +@EV::Async::ISA = "EV::Watcher"; @EV::Loop::Default::ISA = "EV::Loop"; @@ -125,12 +132,20 @@ Must be called after a fork in the child, before entering or continuing the event loop. An alternative is to use C which calls -this fucntion automatically, at some performance loss (refer to the libev +this function automatically, at some performance loss (refer to the libev documentation). +=item $loop->loop_verify + +Calls C to make internal consistency checks (for debugging +libev) and abort the program if any data structures wree found to be +corrupted. + =item $loop = EV::default_loop [$flags] -Return the default loop (which is a singleton object). +Return the default loop (which is a singleton object). Since this module +already creates the default loop with default flags, specifying flags here +will not have any effect unless you destroy the default loop. =back @@ -535,7 +550,7 @@ at January 1st 2011 then it will run when the system time reaches or surpasses this time. -=item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0) +=item * repeating interval timer ($interval > 0, $reschedule_cb = 0) In this mode the watcher will always be scheduled to time out at the next C<$at + N * $interval> time (for some integer N) and then repeat, @@ -563,13 +578,14 @@ time as second argument. I. If you need to stop it, return 1e30 and stop it -afterwards. +watcher, ever, and MUST NOT call any event loop functions or methods>. If +you need to stop it, return 1e30 and stop it afterwards. You may create +and start a C watcher for this task. It must return the next time to trigger, based on the passed time value -(that is, the lowest time value larger than to the second argument). It -will usually be called just before the callback will be triggered, but -might be called at other times, too. +(that is, the lowest time value larger than or equal to to the second +argument). It will usually be called just before the callback will be +triggered, but might be called at other times, too. This can be used to create very complex timers, such as a timer that triggers on each midnight, local time (actually 24 hours after the last @@ -646,16 +662,18 @@ =over 4 -=item $w = EV::child $pid, $callback +=item $w = EV::child $pid, $trace, $callback -=item $w = EV::child_ns $pid, $callback +=item $w = EV::child_ns $pid, $trace, $callback -=item $w = $loop->child ($pid, $callback) +=item $w = $loop->child ($pid, $trace, $callback) -=item $w = $loop->child_ns ($pid, $callback) +=item $w = $loop->child_ns ($pid, $trace, $callback) -Call the callback when a status change for pid C<$pid> (or any pid if -C<$pid> is 0) has been received. More precisely: when the process receives +Call the callback when a status change for pid C<$pid> (or any pid +if C<$pid> is 0) has been received (a status change happens when the +process terminates or is killed, or, when trace is true, additionally when +it is stopped or continued). More precisely: when the process receives a C, EV will fetch the outstanding exit/wait status for all changed/zombie children and call the callback. @@ -672,15 +690,13 @@ The C variant doesn't start (activate) the newly created watcher. -=item $w->set ($pid) +=item $w->set ($pid, $trace) Reconfigures the watcher, see the constructor above for details. Can be called at any time. =item $current_pid = $w->pid -=item $old_pid = $w->pid ($new_pid) - Returns the previously set process id and optionally set a new one. =item $exit_status = $w->rstatus @@ -970,6 +986,28 @@ =back +=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. + +It is, however, possible to use them from the XS level. + +Please see the libev documentation for further details. + +=over 4 + +=item $w = EV::async $callback + +=item $w = EV::async_ns $callback + +=item $w->send + +=item $bool = $w->async_pending + +=back + =head1 PERL SIGNALS @@ -1028,7 +1066,8 @@ 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). +coroutines with EV), L (asynchronous SNMP), L for +event-loop agnostic and portable event driven programming. =head1 AUTHOR