--- cvsroot/EV/README 2009/04/28 00:50:57 1.32 +++ 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. @@ -237,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 @@ -265,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, @@ -284,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 @@ -360,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 :). @@ -561,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 @@ -746,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 @@ -793,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 @@ -822,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) @@ -831,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] @@ -849,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. @@ -879,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 @@ -902,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