--- cvsroot/EV/README 2007/11/28 19:22:16 1.14 +++ cvsroot/EV/README 2007/12/08 14:44:21 1.17 @@ -58,7 +58,8 @@ below is comprehensive, one might also consult the documentation of libev itself () for more subtle details on watcher semantics or some discussion on the available - backends, or how to force a specific backend with "LIBEV_FLAGS". + backends, or how to force a specific backend with "LIBEV_FLAGS", or just + about in any case because it has much more detailed information. BASIC INTERFACE $EV::DIED @@ -97,6 +98,10 @@ When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as fast as possible. + $count = EV::loop_count + Return the number of times the event loop has polled for new events. + Sometiems useful as a generation counter. + EV::once $fh_or_undef, $events, $timeout, $cb->($revents) This function rolls together an I/O and a timer watcher for a single one-shot event without the need for managing a watcher object. @@ -119,6 +124,16 @@ either of them triggers, then they will be stopped and freed, and the callback invoked. + EV::feed_fd_event ($fd, $revents) + Feed an event on a file descriptor into EV. EV will react to this + call as if the readyness notifications specified by $revents (a + combination of "EV::READ" and "EV::WRITE") happened on the file + descriptor $fd. + + EV::feed_signal_event ($signal) + Feed a signal event into EV. EV will react to this call as if the + signal specified by $signal had occured. + 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, @@ -137,7 +152,7 @@ Each watcher type has its associated bit in revents, so you can use the 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 IO + 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). @@ -165,8 +180,8 @@ $w->stop Stop a watcher if it is active. Also clear any pending events (events that have been received but that didn't yet result in a - callback invocation), regardless of wether the watcher was active or - not. + callback invocation), regardless of whether the watcher was active + or not. $bool = $w->is_active Returns true if the watcher is active, false otherwise. @@ -199,9 +214,19 @@ Note that the priority semantics have not yet been fleshed out and are subject to almost certain change. - $w->trigger ($revents) + $w->invoke ($revents) Call the callback *now* with the given event mask. + $w->feed_event ($revents) + Feed some events on this watcher into EV. EV will react to this call + as if the watcher had received the given $revents mask. + + $revents = $w->clear_pending + If the watcher is pending, this function returns clears its pending + status and returns its $revents bitset (as if its callback was + invoked). If the watcher isn't pending it does nothing and returns + 0. + $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). @@ -225,7 +250,7 @@ The initial value for keepalive is true (enabled), and you cna change it any time. - Example: Register an IO watcher for some UDP socket but do not keep + Example: Register an I/O watcher for some UDP socket but do not keep the event loop from running just because of that watcher. my $udp_socket = ... @@ -235,7 +260,7 @@ WATCHER TYPES Each of the following subsections describes a single watcher type. - IO WATCHERS - is this file descriptor readable or writable? + I/O WATCHERS - is this file descriptor readable or writable? $w = EV::io $fileno_or_fh, $eventmask, $callback $w = EV::io_ns $fileno_or_fh, $eventmask, $callback As long as the returned watcher object is alive, call the $callback @@ -522,12 +547,25 @@ IDLE WATCHERS - when you've got nothing better to do... $w = EV::idle $callback $w = EV::idle_ns $callback - Call the callback when there are no pending io, timer/periodic, - signal or child events, i.e. when the process is idle. + Call the callback when there are no other pending watchers of the + same or higher priority (excluding check, prepare and other idle + watchers of the same or lower priority, of course). They are called + idle watchers because when the watcher is the highest priority + pending event in the process, the process is considered to be idle + at that priority. + + If you want a watcher that is only ever called when *no* other + events are outstanding you have to set the priority to "EV::MINPRI". The process will not block as long as any idle watchers are active, and they will be called repeatedly until stopped. + For example, if you have idle watchers at priority 0 and 1, and an + I/O watcher at priority 0, then the idle watcher at priority 1 and + the I/O watcher will always run when ready. Only when the idle + watcher at priority 1 is stopped and the I/O watcher at priority 0 + is not pending with the 0-priority idle watcher be invoked. + The "idle_ns" variant doesn't start (activate) the newly created watcher. @@ -565,7 +603,7 @@ # make the dispatcher handle any outstanding stuff ... not shown - # create an IO watcher for each and every socket + # create an I/O watcher for each and every socket @snmp_watcher = ( (map { EV::io $_, EV::READ, sub { } } keys %{ $dispatcher->{_descriptors} }), @@ -609,6 +647,24 @@ The "fork_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 + handled when Perl runs, which means your signal handler might be invoked + only the next time an event callback is invoked. + + The solution is to use EV signal watchers (see "EV::signal"), which will + ensure proper operations with regards to other event watchers. + + If you cannot do this for whatever reason, you can also force a watcher + to be called on every event loop iteration by installing a "EV::check" + watcher: + + my $async_check = EV::check sub { }; + + This ensures that perl shortly gets into control for a short time, and + also ensures 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 @@ -632,7 +688,8 @@ course. SEE ALSO - EV::DNS. + EV::ADNS (asynchronous dns), Glib::EV (makes Glib/Gtk2 use EV as event + loop), Coro::EV (efficient coroutines with EV). AUTHOR Marc Lehmann