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

Comparing EV/EV.pm (file contents):
Revision 1.19 by root, Thu Nov 1 11:43:10 2007 UTC vs.
Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC

1=head1 NAME 1=head1 NAME
2 2
3EV - perl interface to libevent, monkey.org/~provos/libevent/ 3EV - perl interface to libev, a high performance full-featured event loop
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use EV; 7 use EV;
8 8
9 # TIMER 9 # TIMERS
10 10
11 my $w = EV::timer 2, 0, sub { 11 my $w = EV::timer 2, 0, sub {
12 warn "is called after 2s"; 12 warn "is called after 2s";
13 }; 13 };
14 14
… …
16 warn "is called roughly every 2s (repeat = 1)"; 16 warn "is called roughly every 2s (repeat = 1)";
17 }; 17 };
18 18
19 undef $w; # destroy event watcher again 19 undef $w; # destroy event watcher again
20 20
21 my $w = EV::timer_abs 0, 60, sub { 21 my $w = EV::periodic 0, 60, sub {
22 warn "is called every minute, on the minute, exactly"; 22 warn "is called every minute, on the minute, exactly";
23 }; 23 };
24 24
25 # IO 25 # IO
26 26
27 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub { 27 my $w = EV::io *STDIN, EV::READ, sub {
28 my ($w, $revents) = @_; # all callbacks get the watcher object and event mask 28 my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
29 if ($revents & EV::TIMEOUT) {
30 warn "nothing received on stdin for 10 seconds, retrying";
31 } else {
32 warn "stdin is readable, you entered: ", <STDIN>; 29 warn "stdin is readable, you entered: ", <STDIN>;
33 }
34 };
35 $w->timeout (10);
36
37 my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
38 my ($w, $revents) = @_;
39 if ($revents & EV::TIMEOUT) {
40 warn "nothing entered within 30 seconds, bye bye.\n";
41 $w->stop;
42 } else {
43 my $line = <STDIN>;
44 warn "you entered something, you again have 30 seconds.\n";
45 }
46 }; 30 };
47 31
48 # SIGNALS 32 # SIGNALS
49 33
50 my $w = EV::signal 'QUIT', sub { 34 my $w = EV::signal 'QUIT', sub {
… …
60 my $w = EV::child 666, sub { 44 my $w = EV::child 666, sub {
61 my ($w, $revents, $status) = @_; 45 my ($w, $revents, $status) = @_;
62 }; 46 };
63 47
64 # MAINLOOP 48 # MAINLOOP
65 EV::dispatch; # loop as long as watchers are active 49 EV::loop; # loop until EV::loop_done is called
66 EV::loop; # the same thing
67 EV::loop EV::LOOP_ONESHOT; # block until some events could be handles 50 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
68 EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait 51 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
69 52
70=head1 DESCRIPTION 53=head1 DESCRIPTION
71 54
72This module provides an interface to libev 55This module provides an interface to libev
73(L<http://software.schmorp.de/pkg/libev.html>). You probably should 56(L<http://software.schmorp.de/pkg/libev.html>).
74acquaint yourself with its documentation and source code to be able to use
75this module fully.
76 57
77=cut 58=cut
78 59
79package EV; 60package EV;
80 61
… …
97 78
98=head1 BASIC INTERFACE 79=head1 BASIC INTERFACE
99 80
100=over 4 81=over 4
101 82
102=item $EV::NPRI
103
104How many priority levels are available.
105
106=item $EV::DIED 83=item $EV::DIED
107 84
108Must contain a reference to a function that is called when a callback 85Must contain a reference to a function that is called when a callback
109throws an exception (with $@ containing thr error). The default prints an 86throws an exception (with $@ containing thr error). The default prints an
110informative message and continues. 87informative message and continues.
111 88
112If this callback throws an exception it will be silently ignored. 89If this callback throws an exception it will be silently ignored.
113 90
91=item $time = EV::time
92
93Returns the current time in (fractional) seconds since the epoch.
94
114=item $time = EV::now 95=item $time = EV::now
115 96
116Returns the time in (fractional) seconds since the epoch. 97Returns the time the last event loop iteration has been started. This
98is the time that (relative) timers are based on, and refering to it is
99usually faster then calling EV::time.
117 100
118=item $version = EV::version
119
120=item $method = EV::method 101=item $method = EV::ev_method
121 102
122Return version string and event polling method used. 103Returns an integer describing the backend used by libev (EV::METHOD_SELECT
104or EV::METHOD_EPOLL).
123 105
124=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT 106=item EV::loop [$flags]
125 107
126=item EV::loopexit $after 108Begin checking for events and calling callbacks. It returns when a
109callback calls EV::loop_done.
127 110
128Exit any active loop or dispatch after C<$after> seconds or immediately if 111The $flags argument can be one of the following:
129C<$after> is missing or zero.
130 112
131=item EV::dispatch 113 0 as above
114 EV::LOOP_ONESHOT block at most once (wait, but do not loop)
115 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
132 116
133Same as C<EV::loop 0>. 117=item EV::loop_done [$how]
134 118
135=item EV::event $callback 119When called with no arguments or an argument of 1, makes the innermost
120call to EV::loop return.
136 121
137Creates a new event watcher waiting for nothing, calling the given callback. 122When called with an agrument of 2, all calls to EV::loop will return as
123fast as possible.
138 124
125=back
126
127=head2 WATCHER
128
129A watcher is an object that gets created to record your interest in some
130event. For instance, if you want to wait for STDIN to become readable, you
131would create an EV::io watcher for that:
132
133 my $watcher = EV::io *STDIN, EV::READ, sub {
134 my ($watcher, $revents) = @_;
135 warn "yeah, STDIN should not be readable without blocking!\n"
136 };
137
138All watchers can be active (waiting for events) or inactive (paused). Only
139active watchers will have their callbacks invoked. All callbacks will be
140called with at least two arguments: the watcher and a bitmask of received
141events.
142
143Each watcher type has its associated bit in revents, so you can use the
144same callback for multiple watchers. The event mask is named after the
145type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
146EV::periodic sets EV::PERIODIC and so on, with the exception of IO events
147(which can set both EV::READ and EV::WRITE bits), and EV::timer (which
148uses EV::TIMEOUT).
149
150In the rare case where one wants to create a watcher but not start it at
151the same time, each constructor has a variant with a trailing C<_ns> in
152its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
153
154Please note that a watcher will automatically be stopped when the watcher
155object is returned, so you I<need> to keep the watcher objects returned by
156the constructors.
157
158=head2 WATCHER TYPES
159
160Now lets move to the existing watcher types and asociated methods.
161
162The following methods are available for all watchers. Then followes a
163description of each watcher constructor (EV::io, EV::timer, EV::periodic,
164EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
165any type-specific methods (if any).
166
167=over 4
168
169=item $w->start
170
171Starts a watcher if it isn't active already. Does nothing to an already
172active watcher. By default, all watchers start out in the active state
173(see the description of the C<_ns> variants if you need stopped watchers).
174
175=item $w->stop
176
177Stop a watcher if it is active. Also clear any pending events (events that
178have been received but that didn't yet result in a callback invocation),
179regardless of wether the watcher was active or not.
180
181=item $bool = $w->is_active
182
183Returns true if the watcher is active, false otherwise.
184
185=item $current_cb = $w->cb
186
187=item $old_cb = $w->cb ($new_cb)
188
189Queries the callback on the watcher and optionally changes it. You cna do
190this at any time.
191
192=item $w->trigger ($revents)
193
194Call the callback *now* with the given event mask.
195
196
139=item my $w = EV::io $fileno_or_fh, $eventmask, $callback 197=item $w = EV::io $fileno_or_fh, $eventmask, $callback
140 198
141=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 199=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
142 200
143As long as the returned watcher object is alive, call the C<$callback> 201As long as the returned watcher object is alive, call the C<$callback>
144when the events specified in C<$eventmask> happen. Initially, the timeout 202when the events specified in C<$eventmask>.
145is disabled.
146 203
147You can additionall set a timeout to occur on the watcher, but note that
148this timeout will not be reset when you get an I/O event in the EV::PERSIST
149case, and reaching a timeout will always stop the watcher even in the
150EV::PERSIST case.
151
152If you want a timeout to occur only after a specific time of inactivity, set
153a repeating timeout and do NOT use EV::PERSIST.
154
155Eventmask can be one or more of these constants ORed together: 204The $eventmask can be one or more of these constants ORed together:
156 205
157 EV::READ wait until read() wouldn't block anymore 206 EV::READ wait until read() wouldn't block anymore
158 EV::WRITE wait until write() wouldn't block anymore 207 EV::WRITE wait until write() wouldn't block anymore
159 EV::PERSIST stay active after a (non-timeout) event occured
160 208
161The C<io_ns> variant doesn't add/start the newly created watcher. 209The C<io_ns> variant doesn't start (activate) the newly created watcher.
162 210
163=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback 211=item $w->set ($fileno_or_fh, $eventmask)
164 212
165=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback 213Reconfigures the watcher, see the constructor above for details. Can be
214called at any time.
166 215
167Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was 216=item $current_fh = $w->fh
168a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
169and will automatically be cleared. The watcher will be restarted after each event.
170 217
171If the timeout is zero or undef, no timeout will be set, and a normal 218=item $old_fh = $w->fh ($new_fh)
172watcher (with the persist flag set!) will be created.
173 219
174This has the effect of timing out after the specified period of inactivity 220Returns the previously set filehandle and optionally set a new one.
175has happened.
176 221
177Due to the design of libevent, this is also relatively inefficient, having 222=item $current_eventmask = $w->events
178one or two io watchers and a separate timeout watcher that you reset on
179activity (by calling its C<start> method) is usually more efficient.
180 223
224=item $old_eventmask = $w->events ($new_eventmask)
225
226Returns the previously set event mask and optionally set a new one.
227
228
181=item my $w = EV::timer $after, $repeat, $callback 229=item $w = EV::timer $after, $repeat, $callback
182 230
183=item my $w = EV::timer_ns $after, $repeat, $callback 231=item $w = EV::timer_ns $after, $repeat, $callback
184 232
185Calls the callback after C<$after> seconds. If C<$repeat> is true, the 233Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
186timer will be restarted after the callback returns. This means that the 234the timer will be restarted (with the $repeat value as $after) after the
187callback would be called roughly every C<$after> seconds, prolonged by the 235callback returns.
188time the callback takes.
189 236
237This means that the callback would be called roughly after C<$after>
238seconds, and then every C<$repeat> seconds. "Roughly" because the time of
239callback processing is not taken into account, so the timer will slowly
240drift. If that isn't acceptable, look at EV::periodic.
241
242The timer is based on a monotonic clock, that is if somebody is sitting
243in front of the machine while the timer is running and changes the system
244clock, the timer will nevertheless run (roughly) the same time.
245
190The C<timer_ns> variant doesn't add/start the newly created watcher. 246The C<timer_ns> variant doesn't start (activate) the newly created watcher.
191 247
248=item $w->set ($after, $repeat)
249
250Reconfigures the watcher, see the constructor above for details. Can be at
251any time.
252
253=item $w->again
254
255Similar to the C<start> method, but has special semantics for repeating timers:
256
257If the timer is active and repeating, reset the timeout to occur
258C<$repeat> seconds after now.
259
260If the timer is active and non-repeating, it will be stopped.
261
262If the timer is in active and repeating, start it.
263
264Otherwise do nothing.
265
266This behaviour is useful when you have a timeout for some IO
267operation. You create a timer object with the same value for C<$after> and
268C<$repeat>, and then, in the read/write watcher, run the C<again> method
269on the timeout.
270
271
272=item $w = EV::periodic $at, $interval, $callback
273
192=item my $w = EV::timer_abs $at, $interval, $callback 274=item $w = EV::periodic_ns $at, $interval, $callback
193
194=item my $w = EV::timer_abs_ns $at, $interval, $callback
195 275
196Similar to EV::timer, but the time is given as an absolute point in time 276Similar to EV::timer, but the time is given as an absolute point in time
197(C<$at>), plus an optional C<$interval>. 277(C<$at>), plus an optional C<$interval>.
198 278
199If the C<$interval> is zero, then the callback will be called at the time 279If the C<$interval> is zero, then the callback will be called at the time
200C<$at> if that is in the future, or as soon as possible if its in the 280C<$at> if that is in the future, or as soon as possible if it is in the
201past. It will not automatically repeat. 281past. It will not automatically repeat.
202 282
203If the C<$interval> is nonzero, then the watcher will always be scheduled 283If the C<$interval> is nonzero, then the watcher will always be scheduled
204to time out at the next C<$at + integer * $interval> time. 284to time out at the next C<$at + N * $interval> time.
205 285
206This can be used to schedule a callback to run at very regular intervals, 286This can be used to schedule a callback to run at very regular intervals,
207as long as the processing time is less then the interval (otherwise 287as long as the processing time is less then the interval (otherwise
208obviously events will be skipped). 288obviously events will be skipped).
209 289
210Another way to think about it (for the mathematically inclined) is that 290Another way to think about it (for the mathematically inclined) is that
211C<timer_abs> will try to tun the callback at the next possible time where 291EV::periodic will try to run the callback at the next possible time where
212C<$time = $at (mod $interval)>, regardless of any time jumps. 292C<$time = $at (mod $interval)>, regardless of any time jumps.
213 293
294This periodic timer is based on "wallclock time", that is, if the clock
295changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
296the specified time.
297
214The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 298The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
215 299
300=item $w->set ($at, $interval)
301
302Reconfigures the watcher, see the constructor above for details. Can be at
303any time.
304
305
216=item my $w = EV::signal $signal, $callback 306=item $w = EV::signal $signal, $callback
217 307
218=item my $w = EV::signal_ns $signal, $callback 308=item $w = EV::signal_ns $signal, $callback
219 309
220Call the callback when $signal is received (the signal can be specified 310Call the callback when $signal is received (the signal can be specified
221by number or by name, just as with kill or %SIG). Signal watchers are 311by number or by name, just as with kill or %SIG).
222persistent no natter what.
223 312
224EV will grab the signal for the process (the kernel only allows one 313EV will grab the signal for the process (the kernel only allows one
225component to receive signals) when you start a signal watcher, and 314component to receive a signal at a time) when you start a signal watcher,
226removes it again when you stop it. Pelr does the same when you add/remove 315and removes it again when you stop it. Perl does the same when you
227callbacks to %SIG, so watch out. 316add/remove callbacks to %SIG, so watch out.
228 317
229Unfortunately, only one handler can be registered per signal. Screw 318You can have as many signal watchers per signal as you want.
230libevent.
231 319
232The C<signal_ns> variant doesn't add/start the newly created watcher. 320The C<signal_ns> variant doesn't start (activate) the newly created watcher.
321
322=item $w->set ($signal)
323
324Reconfigures the watcher, see the constructor above for details. Can be at
325any time.
326
327
328=item $w = EV::child $pid, $callback
329
330=item $w = EV::child_ns $pid, $callback
331
332Call the callback when a status change for pid C<$pid> (or any pid
333if C<$pid> is 0) has been received. More precisely: when the process
334receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
335changed/zombie children and call the callback.
336
337Unlike all other callbacks, this callback will be called with an
338additional third argument which is the exit status. See the C<waitpid>
339function for details.
340
341You can have as many pid watchers per pid as you want.
342
343The C<child_ns> variant doesn't start (activate) the newly created watcher.
344
345=item $w->set ($pid)
346
347Reconfigures the watcher, see the constructor above for details. Can be at
348any time.
349
350
351=item $w = EV::idle $callback
352
353=item $w = EV::idle_ns $callback
354
355Call the callback when there are no pending io, timer/periodic, signal or
356child events, i.e. when the process is idle.
357
358The process will not block as long as any idle watchers are active, and
359they will be called repeatedly until stopped.
360
361The C<idle_ns> variant doesn't start (activate) the newly created watcher.
362
363
364=item $w = EV::prepare $callback
365
366=item $w = EV::prepare_ns $callback
367
368Call the callback just before the process would block. You can still
369create/modify any watchers at this point.
370
371See the EV::check watcher, below, for explanations and an example.
372
373The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
374
375
376=item $w = EV::check $callback
377
378=item $w = EV::check_ns $callback
379
380Call the callback just after the process wakes up again (after it has
381gathered events), but before any other callbacks have been invoked.
382
383This is used to integrate other event-based software into the EV
384mainloop: You register a prepare callback and in there, you create io and
385timer watchers as required by the other software. Here is a real-world
386example of integrating Net::SNMP (with some details left out):
387
388 our @snmp_watcher;
389
390 our $snmp_prepare = EV::prepare sub {
391 # do nothing unless active
392 $dispatcher->{_event_queue_h}
393 or return;
394
395 # make the dispatcher handle any outstanding stuff
396
397 # create an IO watcher for each and every socket
398 @snmp_watcher = (
399 (map { EV::io $_, EV::READ, sub { } }
400 keys %{ $dispatcher->{_descriptors} }),
401 );
402
403 # if there are any timeouts, also create a timer
404 push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
405 if $event->[Net::SNMP::Dispatcher::_ACTIVE];
406 };
407
408The callbacks are irrelevant, the only purpose of those watchers is
409to wake up the process as soon as one of those events occurs (socket
410readable, or timer timed out). The corresponding EV::check watcher will then
411clean up:
412
413 our $snmp_check = EV::check sub {
414 # destroy all watchers
415 @snmp_watcher = ();
416
417 # make the dispatcher handle any new stuff
418 };
419
420The callbacks of the created watchers will not be called as the watchers
421are destroyed before this cna happen (remember EV::check gets called
422first).
423
424The C<check_ns> variant doesn't start (activate) the newly created watcher.
233 425
234=back 426=back
235 427
236=head1 THE EV::Event CLASS
237
238All EV functions creating an event watcher (designated by C<my $w =>
239above) support the following methods on the returned watcher object:
240
241=over 4
242
243=item $w->add ($timeout)
244
245Stops and (re-)starts the event watcher, setting the optional timeout to
246the given value, or clearing the timeout if none is given.
247
248=item $w->start
249
250Stops and (re-)starts the event watcher without touching the timeout.
251
252=item $w->del
253
254=item $w->stop
255
256Stop the event watcher if it was started.
257
258=item $current_callback = $w->cb
259
260=item $old_callback = $w->cb ($new_callback)
261
262Return the previously set callback and optionally set a new one.
263
264=item $current_fh = $w->fh
265
266=item $old_fh = $w->fh ($new_fh)
267
268Returns the previously set filehandle and optionally set a new one (also
269clears the EV::SIGNAL flag when setting a filehandle).
270
271=item $current_signal = $w->signal
272
273=item $old_signal = $w->signal ($new_signal)
274
275Returns the previously set signal number and optionally set a new one (also sets
276the EV::SIGNAL flag when setting a signal).
277
278=item $current_eventmask = $w->events
279
280=item $old_eventmask = $w->events ($new_eventmask)
281
282Returns the previously set event mask and optionally set a new one.
283
284=item $w->timeout ($after, $repeat)
285
286Resets the timeout (see C<EV::timer> for details).
287
288=item $w->timeout_abs ($at, $interval)
289
290Resets the timeout (see C<EV::timer_abs> for details).
291
292=item $w->priority_set ($priority)
293
294Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
295
296=back
297
298=head1 THREADS 428=head1 THREADS
299 429
300Threads are not supported by this in any way. Perl pseudo-threads is evil 430Threads are not supported by this in any way. Perl pseudo-threads is evil
301and must die. 431stuff and must die.
302 432
303=cut 433=cut
304 434
305our $DIED = sub { 435our $DIED = sub {
306 warn "EV: error in callback (ignoring): $@"; 436 warn "EV: error in callback (ignoring): $@";
… …
312 442
3131; 4431;
314 444
315=head1 SEE ALSO 445=head1 SEE ALSO
316 446
317 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
318 L<EV::AnyEvent>. 447 L<EV::DNS>, L<EV::AnyEvent>.
319 448
320=head1 AUTHOR 449=head1 AUTHOR
321 450
322 Marc Lehmann <schmorp@schmorp.de> 451 Marc Lehmann <schmorp@schmorp.de>
323 http://home.schmorp.de/ 452 http://home.schmorp.de/

Diff Legend

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