--- EV/README 2008/07/08 18:56:48 1.28 +++ EV/README 2008/11/19 10:33:32 1.31 @@ -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,7 +86,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 *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 @@ -94,13 +97,16 @@ 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,13 @@ $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. $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 +181,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 +225,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 +245,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 +340,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 +750,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 +779,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 +798,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.