--- cvsroot/EV/EV.pm 2008/05/18 10:45:36 1.92 +++ cvsroot/EV/EV.pm 2008/07/12 22:19:22 1.101 @@ -4,54 +4,54 @@ =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 @@ -73,10 +73,11 @@ package EV; +no warnings; use strict; BEGIN { - our $VERSION = '3.33'; + our $VERSION = '3.431'; use XSLoader; XSLoader::load "EV", $VERSION; } @@ -113,6 +114,12 @@ 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] @@ -132,12 +139,22 @@ 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 @@ -277,10 +294,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 @@ -403,7 +420,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 @@ -570,13 +587,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 @@ -944,34 +962,34 @@ 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. @@ -1062,8 +1080,8 @@ =head1 AUTHOR - Marc Lehmann - http://home.schmorp.de/ + Marc Lehmann + http://home.schmorp.de/ =cut