ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
(Generate patch)

Comparing EV/EV.pm (file contents):
Revision 1.47 by root, Fri Nov 23 13:08:55 2007 UTC vs.
Revision 1.53 by root, Sat Nov 24 16:57:30 2007 UTC

… …
48 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 48 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
49 49
50=head1 DESCRIPTION 50=head1 DESCRIPTION
51 51
52This module provides an interface to libev 52This module provides an interface to libev
53(L<http://software.schmorp.de/pkg/libev.html>). 53(L<http://software.schmorp.de/pkg/libev.html>). While the documentation
54below is comprehensive, one might also consult the documentation of libev
55itself (L<http://cvs.schmorp.de/libev/ev.html>) for more subtle details on
56watcher semantics or some discussion on the available backends, or how to
57force a specific backend with C<LIBEV_FLAGS>.
54 58
55=cut 59=cut
56 60
57package EV; 61package EV;
58 62
59use strict; 63use strict;
60 64
61BEGIN { 65BEGIN {
62 our $VERSION = '1.2'; 66 our $VERSION = '1.3';
63 use XSLoader; 67 use XSLoader;
64 XSLoader::load "EV", $VERSION; 68 XSLoader::load "EV", $VERSION;
65} 69}
66 70
67@EV::Io::ISA = 71@EV::IO::ISA =
68@EV::Timer::ISA = 72@EV::Timer::ISA =
69@EV::Periodic::ISA = 73@EV::Periodic::ISA =
70@EV::Signal::ISA = 74@EV::Signal::ISA =
71@EV::Idle::ISA = 75@EV::Idle::ISA =
72@EV::Prepare::ISA = 76@EV::Prepare::ISA =
… …
117innermost call to EV::loop return. 121innermost call to EV::loop return.
118 122
119When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as 123When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
120fast as possible. 124fast as possible.
121 125
122=item EV::once $fh_or_undef, $events, $timeout, $cb->($events) 126=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
123 127
124This function rolls together an I/O and a timer watcher for a single 128This function rolls together an I/O and a timer watcher for a single
125one-shot event without the need for managing a watcher object. 129one-shot event without the need for managing a watcher object.
126 130
127If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events> 131If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
… …
233watchers with higher priority will be invoked first. The valid range of 237watchers with higher priority will be invoked first. The valid range of
234priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default 238priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
235-2). If the priority is outside this range it will automatically be 239-2). If the priority is outside this range it will automatically be
236normalised to the nearest valid priority. 240normalised to the nearest valid priority.
237 241
238The default priority of any newly-created weatcher is 0. 242The default priority of any newly-created watcher is 0.
243
244Note that the priority semantics have not yet been fleshed out and are
245subject to almost certain change.
239 246
240=item $w->trigger ($revents) 247=item $w->trigger ($revents)
241 248
242Call the callback *now* with the given event mask. 249Call the callback *now* with the given event mask.
243 250
251=item $previous_state = $w->keepalive ($bool)
252
253Normally, C<EV::loop> will return when there are no active watchers
254(which is a "deadlock" because no progress can be made anymore). This is
255convinient because it allows you to start your watchers (and your jobs),
256call C<EV::loop> once and when it returns you know that all your jobs are
257finished (or they forgot to register some watchers for their task :).
258
259Sometimes, however, this gets in your way, for example when you the module
260that calls C<EV::loop> (usually the main program) is not the same module
261as a long-living watcher (for example a DNS client module written by
262somebody else even). Then you might want any outstanding requests to be
263handled, but you would not want to keep C<EV::loop> from returning just
264because you happen to have this long-running UDP port watcher.
265
266In this case you can clear the keepalive status, which means that even
267though your watcher is active, it won't keep C<EV::loop> from returning.
268
269The initial value for keepalive is true (enabled), and you cna change it
270any time.
271
272Example: Register an IO watcher for some UDP socket but do not keep the
273event loop from running just because of that watcher.
274
275 my $udp_socket = ...
276 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
277 $udp_watcher->keepalive (0);
244 278
245=item $w = EV::io $fileno_or_fh, $eventmask, $callback 279=item $w = EV::io $fileno_or_fh, $eventmask, $callback
246 280
247=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 281=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
248 282
… …
276 310
277=item $w = EV::timer $after, $repeat, $callback 311=item $w = EV::timer $after, $repeat, $callback
278 312
279=item $w = EV::timer_ns $after, $repeat, $callback 313=item $w = EV::timer_ns $after, $repeat, $callback
280 314
281Calls the callback after C<$after> seconds. If C<$repeat> is non-zero, 315Calls the callback after C<$after> seconds (which may be fractional). If
282the timer will be restarted (with the $repeat value as $after) after the 316C<$repeat> is non-zero, the timer will be restarted (with the $repeat
283callback returns. 317value as $after) after the callback returns.
284 318
285This means that the callback would be called roughly after C<$after> 319This means that the callback would be called roughly after C<$after>
286seconds, and then every C<$repeat> seconds. The timer does his best not 320seconds, and then every C<$repeat> seconds. The timer does his best not
287to drift, but it will not invoke the timer more often then once per event 321to drift, but it will not invoke the timer more often then once per event
288loop iteration, and might drift in other cases. If that isn't acceptable, 322loop iteration, and might drift in other cases. If that isn't acceptable,

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines