--- cvsroot/EV/EV.pm 2007/12/21 05:30:25 1.74 +++ cvsroot/EV/EV.pm 2008/05/26 05:37:18 1.97 @@ -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.42'; 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"; @@ -104,7 +111,7 @@ default loop as this is fastest (perl-wise), best supported by other modules (e.g. AnyEvent or Coro) and most portable event loop. -For specific programs you cna create additional event loops dynamically. +For specific programs you can create additional event loops dynamically. =over 4 @@ -125,9 +132,21 @@ 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). 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 @@ -143,6 +162,20 @@ If this callback throws an exception it will be silently ignored. +=item $flags = EV::supported_backends + +=item $flags = EV::recommended_backends + +=item $flags = EV::embeddable_backends + +Returns the set (see C flags) of backends supported by this +instance of EV, the set of recommended backends (supposed to be good) for +this platform and the set of embeddable backends (see EMBED WATCHERS). + +=item EV::sleep $seconds + +Block the process for the given number of (fractional) seconds. + =item $time = EV::time Returns the current time in (fractional) seconds since the epoch. @@ -210,7 +243,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, +you can expect it to be a combination of C, C, C and C). EV::once doesn't return anything: the watchers stay active till either @@ -230,6 +263,19 @@ Feed a signal event into EV. EV will react to this call as if the signal specified by C<$signal> had occured. +=item EV::set_io_collect_interval $time + +=item $loop->set_io_collect_interval ($time) + +=item EV::set_timeout_collect_interval $time + +=item $loop->set_timeout_collect_interval ($time) + +These advanced functions set the minimum block interval when polling for I/O events and the minimum +wait interval for timer events. See the libev documentation at +L for +a more detailed discussion. + =back @@ -241,7 +287,7 @@ my $watcher = EV::io *STDIN, EV::READ, sub { my ($watcher, $revents) = @_; - warn "yeah, STDIN should not be readable without blocking!\n" + warn "yeah, STDIN should now be readable without blocking!\n" }; All watchers can be active (waiting for events) or inactive (paused). Only @@ -335,8 +381,8 @@ =item $revents = $w->clear_pending -If the watcher is pending, this function returns clears its pending status -and returns its C<$revents> bitset (as if its callback was invoked). If the +If the watcher is pending, this function clears its pending status and +returns its C<$revents> bitset (as if its callback was invoked). If the watcher isn't pending it does nothing and returns C<0>. =item $previous_state = $w->keepalive ($bool) @@ -347,7 +393,7 @@ 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 :). -Sometimes, however, this gets in your way, for example when you the module +Sometimes, however, this gets in your way, for example when the module that calls C (usually the main program) is not the same module as a long-living watcher (for example a DNS client module written by somebody else even). Then you might want any outstanding requests to be @@ -386,7 +432,7 @@ =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback -=item $w = $loop->io 8$fileno_or_fh, $eventmask, $callback) +=item $w = $loop->io ($fileno_or_fh, $eventmask, $callback) =item $w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback) @@ -504,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, @@ -532,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 @@ -615,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. @@ -641,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 @@ -793,7 +840,7 @@ =item $w = $loop->prepare ($callback) -=item $w = $loop->prepare_ns 8$callback) +=item $w = $loop->prepare_ns ($callback) Call the callback just before the process would block. You can still create/modify any watchers at this point. @@ -892,6 +939,76 @@ =back +=head3 EMBED WATCHERS - when one backend isn't enough... + +This is a rather advanced watcher type that lets you embed one event loop +into another (currently only IO events are supported in the embedded +loop, other types of watchers might be handled in a delayed or incorrect +fashion and must not be used). + +See the libev documentation at +L +for more details. + +In short, this watcher is most useful on BSD systems without working +kqueue to still be able to handle a large number of sockets: + + my $socket_loop; + + # check wether we use SELECT or POLL _and_ KQUEUE is supported + if ( + (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT)) + && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE) + ) { + # use kqueue for sockets + $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV; + } + + # use the default loop otherwise + $socket_loop ||= EV::default_loop; + +=over 4 + +=item $w = EV::embed $otherloop, $callback + +=item $w = EV::embed_ns $otherloop, $callback + +=item $w = $loop->embed ($otherloop, $callback) + +=item $w = $loop->embed_ns ($otherloop, $callback) + +Call the callback when the embedded event loop (C<$otherloop>) has any +I/O activity. The C<$callback> should alwas be specified as C in +this version of EV, which means the embedded event loop will be managed +automatically. + +The C variant doesn't start (activate) the newly created watcher. + +=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 While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour @@ -908,8 +1025,8 @@ my $async_check = EV::check sub { }; -This ensures that perl shortly gets into control for a short time, and -also ensures slower overall operation. +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 @@ -949,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