--- cvsroot/EV/README 2008/07/08 18:56:48 1.28 +++ cvsroot/EV/README 2010/10/21 02:46:59 1.36 @@ -4,62 +4,71 @@ SYNOPSIS use EV; - - # TIMERS - - my $w = EV::timer 2, 0, sub { + + # TIMERS + + my $w = EV::timer 2, 0, sub { warn "is called after 2s"; }; - - my $w = EV::timer 2, 2, sub { + + 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 { + + 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 { + + # 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 { + + # SIGNALS + + my $w = EV::signal 'QUIT', sub { warn "sigquit received\n"; }; - - # CHILD/PID STATUS CHANGES - - my $w = EV::child 666, 0, sub { + + # CHILD/PID STATUS CHANGES + + my $w = EV::child 666, 0, sub { my ($w, $revents) = @_; my $status = $w->rstatus; }; - - # STAT CHANGES + + # STAT CHANGES my $w = EV::stat "/etc/passwd", 10, sub { my ($w, $revents) = @_; warn $w->path, " has changed somehow.\n"; }; - - # MAINLOOP + + # 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 +BEFORE YOU START USING THIS MODULE + If you only need timer, I/O, signal, child and idle watchers and not the + advanced functionality of this module, consider using AnyEvent instead, + specifically the simplified API described in AE. + + When used with EV as backend, the AE API is as fast as the native EV + API, but your programs/modules will still run with many other event + loops. + DESCRIPTION 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 +77,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 +95,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 +160,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 +227,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)) @@ -194,7 +246,7 @@ When an error occurs or either the timeout or I/O watcher triggers, then the callback will be called with the received event set (in general you can expect it to be a combination of "EV::ERROR", - "EV::READ", "EV::WRITE" and "EV::TIMEOUT"). + "EV::READ", "EV::WRITE" and "EV::TIMER"). EV::once doesn't return anything: the watchers stay active till either of them triggers, then they will be stopped and freed, and @@ -219,7 +271,16 @@ 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. + + $count = EV::pending_count + $count = $loop->pending_count + Returns the number of currently pending watchers. + + EV::invoke_pending + $loop->invoke_pending + Invoke all currently pending watchers. WATCHER OBJECTS A watcher is an object that gets created to record your interest in some @@ -238,10 +299,9 @@ 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). + events (which can set both EV::READ and EV::WRITE bits). In the rare case where one wants to create a watcher but not start it at the same time, each constructor has a variant with a trailing "_ns" in @@ -316,7 +376,7 @@ $previous_state = $w->keepalive ($bool) Normally, "EV::loop" will return when there are no active watchers (which is a "deadlock" because no progress can be made anymore). - This is convinient because it allows you to start your watchers (and + This is convenient because it allows you to start your watchers (and your jobs), call "EV::loop" once and when it returns you know that all your jobs are finished (or they forgot to register some watchers for their task :). @@ -333,7 +393,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 @@ -517,9 +577,15 @@ SIGNAL WATCHERS - signal me when a signal gets signalled! $w = EV::signal $signal, $callback $w = EV::signal_ns $signal, $callback + $w = $loop->signal ($signal, $callback) + $w = $loop->signal_ns ($signal, $callback) Call the callback when $signal is received (the signal can be specified by number or by name, just as with "kill" or %SIG). + Only one event loop can grab a given signal - attempting to grab the + same signal from two EV loops will crash the program immediately or + cause data corruption. + EV will grab the signal for the process (the kernel only allows one component to receive a signal at a time) when you start a signal watcher, and removes it again when you stop it. Perl does the same @@ -743,7 +809,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,14 +838,14 @@ 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: my $socket_loop; - - # check wether we use SELECT or POLL _and_ KQUEUE is supported + + # 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) @@ -787,26 +853,26 @@ # use kqueue for sockets $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV; } - - # use the default loop otherwise + + # 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. ASYNC WATCHERS - how to wake up another event loop Async watchers are provided by EV, but have little use in perl directly, - as perl neither supports threads nor direct access to signal handlers or - other contexts where they could be of value. + as perl neither supports threads running in parallel nor direct access + to signal handlers or other contexts where they could be of value. It is, however, possible to use them from the XS level. @@ -835,10 +901,11 @@ This ensures that perl gets into control for a short time to handle any pending signals, and also ensures (slightly) slower overall operation. -THREADS - Threads are not supported by this module in any way. Perl pseudo-threads - is evil stuff and must die. As soon as Perl gains real threads I will - work on thread support for it. +ITHREADS + Ithreads are not supported by this module in any way. Perl + pseudo-threads is evil stuff and must die. Real threads as provided by + Coro are fully supported (and enhanced support is available via + Coro::EV). FORK Most of the "improved" event delivering mechanisms of modern operating