--- cvsroot/EV/EV.pm 2008/03/08 16:00:07 1.85 +++ cvsroot/EV/EV.pm 2008/10/23 04:56:49 1.106 @@ -4,73 +4,85 @@ =head1 SYNOPSIS - use EV; - - # TIMERS - - my $w = EV::timer 2, 0, sub { - warn "is called after 2s"; - }; - - my $w = EV::timer 2, 2, sub { - warn "is called roughly every 2s (repeat = 2)"; - }; - - undef $w; # destroy event watcher again - - my $w = EV::periodic 0, 60, 0, sub { - warn "is called every minute, on the minute, exactly"; - }; - - # IO - - my $w = EV::io *STDIN, EV::READ, sub { - my ($w, $revents) = @_; # all callbacks receive the watcher and event mask - warn "stdin is readable, you entered: ", ; - }; - - # SIGNALS - - my $w = EV::signal 'QUIT', sub { - warn "sigquit received\n"; - }; + use EV; + + # TIMERS + + my $w = EV::timer 2, 0, sub { + warn "is called after 2s"; + }; + + my $w = EV::timer 2, 2, sub { + warn "is called roughly every 2s (repeat = 2)"; + }; + + undef $w; # destroy event watcher again + + my $w = EV::periodic 0, 60, 0, sub { + warn "is called every minute, on the minute, exactly"; + }; + + # IO + + my $w = EV::io *STDIN, EV::READ, sub { + my ($w, $revents) = @_; # all callbacks receive the watcher and event mask + warn "stdin is readable, you entered: ", ; + }; + + # SIGNALS + + my $w = EV::signal 'QUIT', sub { + warn "sigquit received\n"; + }; + + # CHILD/PID STATUS CHANGES - # CHILD/PID STATUS CHANGES - - my $w = EV::child 666, 0, sub { - my ($w, $revents) = @_; - my $status = $w->rstatus; - }; - - # STAT CHANGES - my $w = EV::stat "/etc/passwd", 10, sub { - my ($w, $revents) = @_; - warn $w->path, " has changed somehow.\n"; - }; + my $w = EV::child 666, 0, sub { + my ($w, $revents) = @_; + my $status = $w->rstatus; + }; - # MAINLOOP - EV::loop; # loop until EV::unloop is called or all watchers stop - 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 + # STAT CHANGES + my $w = EV::stat "/etc/passwd", 10, sub { + my ($w, $revents) = @_; + warn $w->path, " has changed somehow.\n"; + }; + + # MAINLOOP + EV::loop; # loop until EV::unloop is called or all watchers stop + 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 DESCRIPTION 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. +below is comprehensive, one might also consult the documentation of +libev itself (L or +F) 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. + +=head2 MODULE EXPORTS + +This module does not export any symbols. =cut package EV; +no warnings; use strict; BEGIN { - our $VERSION = '3.1'; + our $VERSION = '3.45'; use XSLoader; XSLoader::load "EV", $VERSION; } @@ -107,31 +119,49 @@ For specific programs you can create additional event loops dynamically. +If you want to take avdantage of kqueue (which often works properly for +sockets only) even though the default loop doesn't enable it, you can +I a kqueue loop into the default loop: running the default loop +will then also service the kqueue loop to some extent. See the example in +the section about embed watchers for an example on how to achieve that. + =over 4 =item $loop = new EV::loop [$flags] -Create a new event loop as per the specified flags. Please refer to the -C function description in the libev documentation -(L) -for more info. +Create a new event loop as per the specified flags. Please refer to +the C function description in the libev documentation +(L, +or locally-installed as F manpage) for more info. The loop will automatically be destroyed when it is no longer referenced by any watcher and the loop object goes out of scope. -Using C is recommended, as only the default event loop -is protected by this module. +If you are not embedding the loop, then Using C +is recommended, as only the default event loop is protected by this +module. If you I embedding this loop in the default loop, this is not +necessary, as C automatically does the right thing on fork. =item $loop->loop_fork 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 were 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 first, which +isn't supported. So in short: don't do it, and if you break it, you get to +keep the pieces. =back @@ -259,8 +289,8 @@ 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. +L +(locally installed as F) for a more detailed discussion. =back @@ -271,10 +301,10 @@ event. For instance, if you want to wait for STDIN to become readable, you would create an EV::io watcher for that: - my $watcher = EV::io *STDIN, EV::READ, sub { - my ($watcher, $revents) = @_; - warn "yeah, STDIN should now be readable without blocking!\n" - }; + my $watcher = EV::io *STDIN, EV::READ, sub { + my ($watcher, $revents) = @_; + warn "yeah, STDIN should now be readable without blocking!\n" + }; All watchers can be active (waiting for events) or inactive (paused). Only active watchers will have their callbacks invoked. All callbacks will be @@ -397,7 +427,7 @@ my $udp_socket = ... my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... }; - $1000udp_watcher->keepalive (0); + $udp_watcher->keepalive (0); =item $loop = $w->loop @@ -564,13 +594,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 @@ -933,39 +964,39 @@ See the libev documentation at L -for more details. +(locally installed as F) 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; + 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 $otherloop[, $callback] -=item $w = EV::embed_ns $otherloop, $callback +=item $w = EV::embed_ns $otherloop[, $callback] -=item $w = $loop->embed ($otherloop, $callback) +=item $w = $loop->embed ($otherloop[, $callback]) -=item $w = $loop->embed_ns ($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. +I/O activity. The C<$callback> is optional: if it is missing, then the +embedded event loop will be managed automatically (which is recommended), +otherwise you have to invoke C yourself. The C variant doesn't start (activate) the newly created watcher. @@ -981,6 +1012,18 @@ 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 @@ -1039,12 +1082,13 @@ 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 - Marc Lehmann - http://home.schmorp.de/ + Marc Lehmann + http://home.schmorp.de/ =cut