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

Comparing EV/EV.pm (file contents):
Revision 1.46 by root, Fri Nov 23 05:00:44 2007 UTC vs.
Revision 1.52 by root, Sat Nov 24 16:20: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
126=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
127
128This function rolls together an I/O and a timer watcher for a single
129one-shot event without the need for managing a watcher object.
130
131If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
132must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
133| EV::WRITE>, indicating the type of I/O event you want to wait for. If
134you do not want to wait for some I/O event, specify C<undef> for
135C<$fh_or_undef> and C<0> for C<$events>).
136
137If timeout is C<undef> or negative, then there will be no
138timeout. Otherwise a EV::timer with this value will be started.
139
140When an error occurs or either the timeout or I/O watcher triggers, then
141the callback will be called with the received event set (in general
142you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
143C<EV::WRITE> and C<EV::TIMEOUT>).
144
145EV::once doesn't return anything: the watchers stay active till either
146of them triggers, then they will be stopped and freed, and the callback
147invoked.
148
122=back 149=back
123 150
124=head2 WATCHER 151=head2 WATCHER
125 152
126A watcher is an object that gets created to record your interest in some 153A watcher is an object that gets created to record your interest in some
… …
210watchers with higher priority will be invoked first. The valid range of 237watchers with higher priority will be invoked first. The valid range of
211priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default 238priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
212-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
213normalised to the nearest valid priority. 240normalised to the nearest valid priority.
214 241
215The 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.
216 246
217=item $w->trigger ($revents) 247=item $w->trigger ($revents)
218 248
219Call the callback *now* with the given event mask. 249Call the callback *now* with the given event mask.
220 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);
221 278
222=item $w = EV::io $fileno_or_fh, $eventmask, $callback 279=item $w = EV::io $fileno_or_fh, $eventmask, $callback
223 280
224=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 281=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
225 282

Diff Legend

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