--- cvsroot/EV/EV.pm 2008/10/02 12:26:25 1.104 +++ cvsroot/EV/EV.pm 2009/04/28 00:50:56 1.115 @@ -59,7 +59,7 @@ (L). While the documentation below is comprehensive, one might also consult the documentation of libev itself (L or -F) for more subtle details on watcher semantics or some +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. @@ -70,6 +70,10 @@ 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; @@ -78,7 +82,7 @@ use strict; BEGIN { - our $VERSION = '3.44'; + our $VERSION = '3.6'; use XSLoader; XSLoader::load "EV", $VERSION; } @@ -115,7 +119,7 @@ For specific programs you can create additional event loops dynamically. -If you want to take avdantage of kqueue (which often works properly for +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 @@ -123,12 +127,12 @@ =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, -or locally-installed as F manpage) for more info. +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. @@ -197,15 +201,57 @@ =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 EV::now_update + +=item $loop->now_update + +Establishes the current time by querying the kernel, updating the time +returned by C in the progress. This is a costly operation and +is usually done automatically within C. + +This function is rarely useful, but when some event callback runs for a +very long time without entering the event loop, updating libev's idea of +the current time is a good idea. + +=item EV::suspend + +=item $loop->suspend + +=item EV::resume + +=item $loop->resume + +These two functions suspend and resume a loop, for use when the loop is +not used for a while and timeouts should not be processed. + +A typical use case would be an interactive program such as a game: When +the user presses C<^Z> to suspend the game and resumes it an hour later it +would be best to handle timeouts as if no time had actually passed while +the program was suspended. This can be achieved by calling C +in your C handler, sending yourself a C and calling +C directly afterwards to resume timer processing. + +Effectively, all C watchers will be delayed by the time spend +between C and C, and all C watchers +will be rescheduled (that is, they will lose any events that would have +occured while suspended). + +After calling C you B call I function on the given +loop other than C, and you B call C +without a previous call to C. + +Calling C/C has the side effect of updating the event +loop time (see C). + =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] @@ -235,7 +281,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) @@ -286,7 +332,7 @@ 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 -(locally installed as F) for a more detailed discussion. +(locally installed as F) for a more detailed discussion. =back @@ -309,7 +355,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). @@ -415,7 +461,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 @@ -919,7 +965,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. @@ -960,7 +1006,7 @@ See the libev documentation at L -(locally installed as F) 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: