--- cvsroot/EV/README 2008/07/08 18:56:48 1.28 +++ cvsroot/EV/README 2009/04/28 00:50:57 1.32 @@ -56,10 +56,10 @@ This module provides an interface to libev (). While the documentation below is comprehensive, one might also consult the documentation of - libev itself () - for more subtle details on watcher semantics or some discussion on the - available backends, or how to force a specific backend with - "LIBEV_FLAGS", or just about in any case because it has much more + libev itself ( or + perldoc EV::libev) for more subtle details on watcher semantics or some + discussion on the available backends, or how to force a specific backend + with "LIBEV_FLAGS", 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 @@ -68,6 +68,9 @@ and still be faster than with any other event loop currently supported in Perl. + MODULE EXPORTS + This module does not export any symbols. + EVENT LOOPS EV supports multiple event loops: There is a single "default event loop" that can handle everything including signals and child watchers, and any @@ -83,24 +86,27 @@ 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 *embed* 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. - $loop = new EV::loop [$flags] + $loop = new EV::Loop [$flags] Create a new event loop as per the specified flags. Please refer to the "ev_loop_new ()" function description in the libev documentation () for more info. + ONS>, or locally-installed as EV::libev 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 "EV::FLAG_FORKCHECK" is recommended, as only the default event - loop is protected by this module. + If you are not embedding the loop, then Using "EV::FLAG_FORKCHECK" + is recommended, as only the default event loop is protected by this + module. If you *are* embedding this loop in the default loop, this + is not necessary, as "EV::embed" automatically does the right thing + on fork. $loop->loop_fork Must be called after a fork in the child, before entering or @@ -145,13 +151,50 @@ $time = EV::now $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 + This is the time that (relative) timers are based on, and referring to it is usually faster then calling EV::time. + EV::now_update + $loop->now_update + Establishes the current time by querying the kernel, updating the + time returned by "EV::now" in the progress. This is a costly + operation and is usually done automatically within "EV::loop". + + 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. + + EV::suspend + $loop->suspend + EV::resume + $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 "^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 "suspend" in your "SIGTSTP" handler, sending + yourself a "SIGSTOP" and calling "resume" directly afterwards to + resume timer processing. + + Effectively, all "timer" watchers will be delayed by the time spend + between "suspend" and "resume", and all "periodic" watchers will be + rescheduled (that is, they will lose any events that would have + occured while suspended). + + After calling "suspend" you must not call *any* function on the + given loop other than "resume", and you must not call "resume" + without a previous call to "suspend". + + Calling "suspend"/"resume" has the side effect of updating the event + loop time (see "now_update"). + $backend = EV::backend $backend = $loop->backend Returns an integer describing the backend used by libev - (EV::METHOD_SELECT or EV::METHOD_EPOLL). + (EV::BACKEND_SELECT or EV::BACKEND_EPOLL). EV::loop [$flags] $loop->loop ([$flags]) @@ -175,7 +218,7 @@ $count = EV::loop_count $count = $loop->loop_count Return the number of times the event loop has polled for new events. - Sometiems useful as a generation counter. + Sometimes useful as a generation counter. EV::once $fh_or_undef, $events, $timeout, $cb->($revents) $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents)) @@ -219,7 +262,8 @@ for I/O events and the minimum wait interval for timer events. See the libev documentation at for a more detailed discussion. + ROLLING_THE_EVENT_LOOP> (locally installed as EV::libev) for a more + detailed discussion. WATCHER OBJECTS A watcher is an object that gets created to record your interest in some @@ -238,7 +282,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). @@ -333,7 +377,7 @@ even though your watcher is active, it won't keep "EV::loop" from returning. - The initial value for keepalive is true (enabled), and you cna + 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 @@ -743,7 +787,7 @@ }; The callbacks of the created watchers will not be called as the - watchers are destroyed before this cna happen (remember EV::check + watchers are destroyed before this can happen (remember EV::check gets called first). The "check_ns" variant doesn't start (activate) the newly created @@ -772,7 +816,7 @@ See the libev documentation at for more details. + _when_one_backend_> (locally installed as EV::libev) 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: @@ -791,14 +835,14 @@ # use the default loop otherwise $socket_loop ||= EV::default_loop; - $w = EV::embed $otherloop, $callback - $w = EV::embed_ns $otherloop, $callback - $w = $loop->embed ($otherloop, $callback) - $w = $loop->embed_ns ($otherloop, $callback) + $w = EV::embed $otherloop[, $callback] + $w = EV::embed_ns $otherloop[, $callback] + $w = $loop->embed ($otherloop[, $callback]) + $w = $loop->embed_ns ($otherloop[, $callback]) Call the callback when the embedded event loop ($otherloop) has any - I/O activity. The $callback should alwas be specified as "undef" in - this version of EV, which means the embedded event loop will be - managed automatically. + I/O activity. The $callback is optional: if it is missing, then the + embedded event loop will be managed automatically (which is + recommended), otherwise you have to invoke "sweep" yourself. The "embed_ns" variant doesn't start (activate) the newly created watcher.