--- cvsroot/EV/README 2008/11/19 10:33:32 1.31 +++ cvsroot/EV/README 2010/10/25 11:30:45 1.38 @@ -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 @@ -68,6 +77,36 @@ and still be faster than with any other event loop currently supported in Perl. + PORTING FROM EV 3.X to 4.X + EV version 4 introduces a number of incompatible changes summarised + here. According to the depreciation strategy used by libev, there is a + compatibility layer in place so programs should continue to run + unchanged (the XS interface lacks this layer, so programs using that one + need to be updated). + + This compatibility layer will be switched off in some future release. + + All changes relevant to Perl are renames of symbols, functions and + methods: + + EV::loop => EV::run + EV::LOOP_NONBLOCK => EV::RUN_NOWAIT + EV::LOOP_ONESHOT => EV::RUN_ONCE + + EV::unloop => EV::break + EV::UNLOOP_CANCEL => EV::BREAK_CANCEL + EV::UNLOOP_ONE => EV::BREAK_ONE + EV::UNLOOP_ALL => EV::BREAK_ALL + + EV::TIMEOUT => EV::TIMER + + EV::loop_count => EV::iteration + EV::loop_depth => EV::depth + EV::loop_verify => EV::verify + + The loop object methods corresponding to the functions above have been + similarly renamed. + MODULE EXPORTS This module does not export any symbols. @@ -93,7 +132,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 @@ -200,7 +276,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 +304,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, @@ -247,8 +331,7 @@ 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, 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 +406,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 :). @@ -524,9 +607,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 @@ -709,7 +798,7 @@ has gathered events), but before any other callbacks have been invoked. - This is used to integrate other event-based software into the EV + This can be used to integrate other event-based software into the EV mainloop: You register a prepare callback and in there, you create io and timer watchers as required by the other software. Here is a real-world example of integrating Net::SNMP (with some details left @@ -756,6 +845,15 @@ The "check_ns" variant doesn't start (activate) the newly created watcher. + EV::CHECK constant issues + Like all other watcher types, there is a bitmask constant for use in + $revents and other places. The "EV::CHECK" is special as it has the + same name as the "CHECK" sub called by Perl. This doesn't cause big + issues on newer perls (beginning with 5.8.9), but it means thatthe + constant must be *inlined*, i.e. runtime calls will not work. That + means that as long as you always "use EV" and then "EV::CHECK" you + are on the safe side. + FORK WATCHERS - the audacity to resume the event loop after a fork Fork watchers are called when a "fork ()" was detected. The invocation is done before the event loop blocks next and before "check" watchers @@ -785,8 +883,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 +892,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 +910,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 +940,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 @@ -865,10 +964,11 @@ course. SEE ALSO - EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event - loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines - with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop - agnostic and portable event driven programming. + EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous + DNS), Glib::EV (makes Glib/Gtk2 use EV as event loop), EV::Glib (embed + Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV + (asynchronous SNMP), AnyEvent for event-loop agnostic and portable event + driven programming. AUTHOR Marc Lehmann