--- cvsroot/EV/README 2008/11/19 10:33:32 1.31 +++ cvsroot/EV/README 2009/07/17 14:49:33 1.33 @@ -4,50 +4,50 @@ 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 @@ -93,7 +93,7 @@ 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_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 @@ -228,6 +265,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, @@ -785,8 +830,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 +839,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 +857,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 +887,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