--- cvsroot/EV/README 2008/10/23 04:56:49 1.30 +++ cvsroot/EV/README 2010/10/21 02:46:59 1.36 @@ -4,54 +4,63 @@ 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 @@ -86,14 +95,14 @@ 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 (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]) @@ -181,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)) @@ -200,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 @@ -228,6 +274,14 @@ 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 event. For instance, if you want to wait for STDIN to become readable, @@ -245,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 @@ -323,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 :). @@ -340,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 @@ -524,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 @@ -750,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 @@ -785,8 +844,8 @@ 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) @@ -794,8 +853,8 @@ # 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] @@ -812,8 +871,8 @@ 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. @@ -842,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