--- EV/README 2007/10/28 06:40:46 1.3 +++ EV/README 2007/11/01 13:33:12 1.5 @@ -2,50 +2,74 @@ EV - perl interface to libevent, monkey.org/~provos/libevent/ SYNOPSIS - use EV; - - # TIMER - - my $w = EV::timer 2, 0, sub { - warn "is called after 2s"; - }; - - my $w = EV::timer 2, 1, sub { - warn "is called roughly every 2s (repeat = 1)"; - }; - - undef $w; # destroy event watcher again - - # IO - - my $w = EV::timer_abs 0, 60, sub { - warn "is called every minute, on the minute, exactly"; - }; - - my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub { - my ($w, $events) = @_; # all callbacks get the watcher object and event mask - if ($events & EV::TIMEOUT) { - warn "nothign received on stdin for 10 seconds, retrying"; - } else { - warn "stdin is readable, you entered: ", ; - } - }; - $w->timeout (10); - - # MAINLOOP - EV::dispatch; # loop as long as watchers are active - EV::loop; # the same thing - EV::loop EV::LOOP_ONCE; - EV::loop EV::LOOP_ONSHOT; + use EV; + + # TIMER + + my $w = EV::timer 2, 0, sub { + warn "is called after 2s"; + }; + + my $w = EV::timer 2, 1, sub { + warn "is called roughly every 2s (repeat = 1)"; + }; + + undef $w; # destroy event watcher again + + my $w = EV::timer_abs 0, 60, sub { + warn "is called every minute, on the minute, exactly"; + }; + + # IO + + my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub { + my ($w, $revents) = @_; # all callbacks get the watcher object and event mask + if ($revents & EV::TIMEOUT) { + warn "nothing received on stdin for 10 seconds, retrying"; + } else { + warn "stdin is readable, you entered: ", ; + } + }; + $w->timeout (10); + + my $w = EV::timed_io \*STDIN, EV::READ, 30, sub { + my ($w, $revents) = @_; + if ($revents & EV::TIMEOUT) { + warn "nothing entered within 30 seconds, bye bye.\n"; + $w->stop; + } else { + my $line = ; + warn "you entered something, you again have 30 seconds.\n"; + } + }; + + # SIGNALS + + my $w = EV::signal 'QUIT', sub { + warn "sigquit received\n"; + }; + + my $w = EV::signal 3, sub { + warn "sigquit received (this is GNU/Linux, right?)\n"; + }; + + # CHILD/PID STATUS CHANGES + + my $w = EV::child 666, sub { + my ($w, $revents, $status) = @_; + }; + + # MAINLOOP + EV::dispatch; # loop as long as watchers are active + EV::loop; # the same thing + EV::loop EV::LOOP_ONESHOT; # block until some events could be handles + EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait DESCRIPTION - This module provides an interface to libevent - (). You probably should acquaint - yourself with its documentation and source code to be able to use this - module fully. - - Please note thta this module disables the libevent EPOLL method by - default, see BUGS, below, if you need to enable it. + This module provides an interface to libev + (). You probably should + acquaint yourself with its documentation and source code to be able to + use this module fully. BASIC INTERFACE $EV::NPRI @@ -83,7 +107,7 @@ when the events specified in $eventmask happen. Initially, the timeout is disabled. - Youc an additionall set a timeout to occur on the watcher, but note + You can additionall set a timeout to occur on the watcher, but note that this timeout will not be reset when you get an I/O event in the EV::PERSIST case, and reaching a timeout will always stop the watcher even in the EV::PERSIST case. @@ -99,6 +123,24 @@ The "io_ns" variant doesn't add/start the newly created watcher. + my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback + my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback + Same as "io" and "io_ns", but also specifies a timeout (as if there + was a call to "$w->timeout ($timout, 1)". The persist flag is not + allowed and will automatically be cleared. The watcher will be + restarted after each event. + + If the timeout is zero or undef, no timeout will be set, and a + normal watcher (with the persist flag set!) will be created. + + This has the effect of timing out after the specified period of + inactivity has happened. + + Due to the design of libevent, this is also relatively inefficient, + having one or two io watchers and a separate timeout watcher that + you reset on activity (by calling its "start" method) is usually + more efficient. + my $w = EV::timer $after, $repeat, $callback my $w = EV::timer_ns $after, $repeat, $callback Calls the callback after $after seconds. If $repeat is true, the @@ -132,9 +174,19 @@ The "timer_abs_ns" variant doesn't add/start the newly created watcher. - my $w = EV::signal $signum, $callback - my $w = EV::signal_ns $signum, $callback - Call the callback when signal $signum is received. + my $w = EV::signal $signal, $callback + my $w = EV::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). Signal + watchers are persistent no natter what. + + EV will grab the signal for the process (the kernel only allows one + component to receive signals) when you start a signal watcher, and + removes it again when you stop it. Pelr does the same when you + add/remove callbacks to %SIG, so watch out. + + Unfortunately, only one handler can be registered per signal. Screw + libevent. The "signal_ns" variant doesn't add/start the newly created watcher. @@ -161,7 +213,13 @@ $current_fh = $w->fh $old_fh = $w->fh ($new_fh) - Returns the previously set filehandle and optionally set a new one. + Returns the previously set filehandle and optionally set a new one + (also clears the EV::SIGNAL flag when setting a filehandle). + + $current_signal = $w->signal + $old_signal = $w->signal ($new_signal) + Returns the previously set signal number and optionally set a new + one (also sets the EV::SIGNAL flag when setting a signal). $current_eventmask = $w->events $old_eventmask = $w->events ($new_eventmask) @@ -177,17 +235,9 @@ Set the priority of the watcher to $priority (0 <= $priority < $EV::NPRI). -BUGS - Lots. Libevent itself isn't well tested and rather buggy, and this - module is quite new at the moment. - - Please note that the epoll method is not, in general, reliable in - programs that use fork (even if no libveent calls are being made in the - forked process). If your program behaves erratically, try setting the - environment variable "EVENT_NOEPOLL" first when running the program. - - In general, if you fork, then you can only use the EV module in one of - the children. +THREADS + Threads are not supported by this in any way. Perl pseudo-threads is + evil and must die. SEE ALSO L, L, L, L.