--- cvsroot/EV/EV.pm 2008/05/31 23:17:50 1.98 +++ cvsroot/EV/EV.pm 2009/03/14 16:24:27 1.113 @@ -57,11 +57,12 @@ 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 @@ -69,14 +70,19 @@ 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.42'; + our $VERSION = '3.53'; use XSLoader; XSLoader::load "EV", $VERSION; } @@ -113,20 +119,28 @@ For specific programs you can create additional event loops dynamically. +If you want to take advantage 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] +=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 @@ -138,14 +152,16 @@ =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 +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). 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. +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 @@ -185,15 +201,15 @@ =item $time = $loop->now Returns the time the last event loop iteration has been started. This -is the time that (relative) timers are based on, and refering to it is +is the time that (relative) timers are based on, and referring to it is usually faster then calling EV::time. =item $backend = EV::backend =item $backend = $loop->backend -Returns an integer describing the backend used by libev (EV::METHOD_SELECT -or EV::METHOD_EPOLL). +Returns an integer describing the backend used by libev (EV::BACKEND_SELECT +or EV::BACKEND_EPOLL). =item EV::loop [$flags] @@ -223,7 +239,7 @@ =item $count = $loop->loop_count Return the number of times the event loop has polled for new -events. Sometiems useful as a generation counter. +events. Sometimes useful as a generation counter. =item EV::once $fh_or_undef, $events, $timeout, $cb->($revents) @@ -273,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 @@ -297,7 +313,7 @@ Each watcher type has its associated bit in revents, so you can use the 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, +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). @@ -403,7 +419,7 @@ In this case you can clear the keepalive status, which means that even though your watcher is active, it won't keep C from returning. -The initial value for keepalive is true (enabled), and you cna change it +The initial value for keepalive is true (enabled), and you can change it any time. Example: Register an I/O watcher for some UDP socket but do not keep the @@ -907,7 +923,7 @@ }; The callbacks of the created watchers will not be called as the watchers -are destroyed before this cna happen (remember EV::check gets called +are destroyed before this can happen (remember EV::check gets called first). The C variant doesn't start (activate) the newly created watcher. @@ -948,7 +964,7 @@ 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: @@ -969,18 +985,18 @@ =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.