--- cvsroot/EV/README 2007/12/22 12:05:42 1.20 +++ cvsroot/EV/README 2008/01/28 12:24:05 1.22 @@ -4,39 +4,39 @@ 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 + + # CHILD/PID STATUS CHANGES - my $w = EV::child 666, sub { + my $w = EV::child 666, 0, sub { my ($w, $revents) = @_; my $status = $w->rstatus; }; @@ -46,8 +46,8 @@ 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 @@ -74,7 +74,7 @@ default loop as this is fastest (perl-wise), best supported by other modules (e.g. AnyEvent or Coro) and most portable event loop. - For specific programs you cna create additional event loops dynamically. + For specific programs you can create additional event loops dynamically. $loop = new EV::loop [$flags] Create a new event loop as per the specified flags. Please refer to @@ -94,6 +94,9 @@ "EV::FLAG_FORKCHECK" which calls this fucntion automatically, at some performance loss (refer to the libev documentation). + $loop = EV::default_loop [$flags] + Return the default loop (which is a singleton object). + BASIC INTERFACE $EV::DIED Must contain a reference to a function that is called when a @@ -102,6 +105,17 @@ If this callback throws an exception it will be silently ignored. + $flags = EV::supported_backends + $flags = EV::recommended_backends + $flags = EV::embeddable_backends + Returns the set (see "EV::BACKEND_*" flags) of backends supported by + this instance of EV, the set of recommended backends (supposed to be + good) for this platform and the set of embeddable backends (see + EMBED WATCHERS). + + EV::sleep $seconds + Block the process for the given number of (fractional) seconds. + $time = EV::time Returns the current time in (fractional) seconds since the epoch. @@ -174,6 +188,16 @@ Feed a signal event into EV. EV will react to this call as if the signal specified by $signal had occured. + EV::set_io_collect_interval $time + $loop->set_io_collect_interval ($time) + EV::set_timeout_collect_interval $time + $loop->set_timeout_collect_interval ($time) + These advanced functions set the minimum block interval when polling + for I/O events and the minimum wait interval for timer events. See + the libev documentation at + for a more detailed discussion. + 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, @@ -392,13 +416,15 @@ It has three distinct "modes": - * absolute timer ($interval = $reschedule_cb = 0) + * absolute timer ($interval = $reschedule_cb = 0) + This time simply fires at the wallclock time $at and doesn't repeat. It will not adjust when a time jump occurs, that is, if it is to be run at January 1st 2011 then it will run when the system time reaches or surpasses this time. - * non-repeating interval timer ($interval > 0, $reschedule_cb = 0) + * non-repeating interval timer ($interval > 0, $reschedule_cb = 0) + In this mode the watcher will always be scheduled to time out at the next "$at + N * $interval" time (for some integer N) and then repeat, regardless of any time jumps. @@ -417,7 +443,8 @@ at the next possible time where "$time = $at (mod $interval)", regardless of any time jumps. - * manual reschedule mode ($reschedule_cb = coderef) + * manual reschedule mode ($reschedule_cb = coderef) + In this mode $interval and $at are both being ignored. Instead, each time the periodic watcher gets scheduled, the reschedule callback ($reschedule_cb) will be called with the watcher as @@ -488,14 +515,17 @@ optionally set a new one. CHILD WATCHERS - watch out for process status changes - $w = EV::child $pid, $callback - $w = EV::child_ns $pid, $callback - $w = $loop->child ($pid, $callback) - $w = $loop->child_ns ($pid, $callback) + $w = EV::child $pid, $trace, $callback + $w = EV::child_ns $pid, $trace, $callback + $w = $loop->child ($pid, $trace, $callback) + $w = $loop->child_ns ($pid, $trace, $callback) Call the callback when a status change for pid $pid (or any pid if - $pid is 0) has been received. More precisely: when the process - receives a "SIGCHLD", EV will fetch the outstanding exit/wait status - for all changed/zombie children and call the callback. + $pid is 0) has been received (a status change happens when the + process terminates or is killed, or, when trace is true, + additionally when it is stopped or continued). More precisely: when + the process receives a "SIGCHLD", EV will fetch the outstanding + exit/wait status for all changed/zombie children and call the + callback. It is valid (and fully supported) to install a child watcher after a child has exited but before the event loop has started its next @@ -512,12 +542,11 @@ The "child_ns" variant doesn't start (activate) the newly created watcher. - $w->set ($pid) + $w->set ($pid, $trace) Reconfigures the watcher, see the constructor above for details. Can be called at any time. $current_pid = $w->pid - $old_pid = $w->pid ($new_pid) Returns the previously set process id and optionally set a new one. $exit_status = $w->rstatus @@ -710,6 +739,45 @@ The "fork_ns" variant doesn't start (activate) the newly created watcher. + EMBED WATCHERS - when one backend isn't enough... + This is a rather advanced watcher type that lets you embed one event + loop into another (currently only IO events are supported in the + embedded loop, other types of watchers might be handled in a delayed or + incorrect fashion and must not be used). + + See the libev documentation at + 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 + if ( + (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT)) + && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE) + ) { + # use kqueue for sockets + $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV; + } + + # 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) + 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. + + The "embed_ns" variant doesn't start (activate) the newly created + watcher. + PERL SIGNALS While Perl signal handling (%SIG) is not affected by EV, the behaviour with EV is as the same as any other C library: Perl-signals will only be