ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
Revision: 1.36
Committed: Sun Nov 11 04:14:09 2007 UTC (16 years, 6 months ago) by root
Branch: MAIN
CVS Tags: rel-0_8
Changes since 1.35: +1 -1 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3 root 1.20 EV - perl interface to libev, a high performance full-featured event loop
4 root 1.1
5     =head1 SYNOPSIS
6    
7 root 1.11 use EV;
8    
9 root 1.20 # TIMERS
10 root 1.11
11     my $w = EV::timer 2, 0, sub {
12     warn "is called after 2s";
13     };
14    
15 root 1.35 my $w = EV::timer 2, 2, sub {
16     warn "is called roughly every 2s (repeat = 2)";
17 root 1.11 };
18    
19     undef $w; # destroy event watcher again
20    
21 root 1.30 my $w = EV::periodic 0, 60, 0, sub {
22 root 1.11 warn "is called every minute, on the minute, exactly";
23     };
24    
25     # IO
26    
27 root 1.20 my $w = EV::io *STDIN, EV::READ, sub {
28 root 1.35 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29 root 1.20 warn "stdin is readable, you entered: ", <STDIN>;
30 root 1.11 };
31    
32     # SIGNALS
33    
34     my $w = EV::signal 'QUIT', sub {
35     warn "sigquit received\n";
36     };
37    
38 root 1.16 # CHILD/PID STATUS CHANGES
39    
40     my $w = EV::child 666, sub {
41 root 1.27 my ($w, $revents) = @_;
42     my $status = $w->rstatus;
43 root 1.16 };
44 root 1.11
45     # MAINLOOP
46 root 1.35 EV::loop; # loop until EV::loop_done is called or all watchers stop
47 root 1.20 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
48     EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
49 root 1.2
50 root 1.1 =head1 DESCRIPTION
51    
52 root 1.16 This module provides an interface to libev
53 root 1.20 (L<http://software.schmorp.de/pkg/libev.html>).
54 root 1.1
55     =cut
56    
57     package EV;
58    
59     use strict;
60    
61     BEGIN {
62 root 1.36 our $VERSION = '0.8';
63 root 1.1 use XSLoader;
64     XSLoader::load "EV", $VERSION;
65     }
66    
67 root 1.18 @EV::Io::ISA =
68     @EV::Timer::ISA =
69     @EV::Periodic::ISA =
70     @EV::Signal::ISA =
71     @EV::Idle::ISA =
72     @EV::Prepare::ISA =
73     @EV::Check::ISA =
74 root 1.17 @EV::Child::ISA = "EV::Watcher";
75 root 1.15
76 root 1.8 =head1 BASIC INTERFACE
77 root 1.1
78     =over 4
79    
80 root 1.8 =item $EV::DIED
81    
82     Must contain a reference to a function that is called when a callback
83     throws an exception (with $@ containing thr error). The default prints an
84     informative message and continues.
85    
86     If this callback throws an exception it will be silently ignored.
87    
88 root 1.20 =item $time = EV::time
89    
90     Returns the current time in (fractional) seconds since the epoch.
91    
92 root 1.2 =item $time = EV::now
93    
94 root 1.20 Returns the time the last event loop iteration has been started. This
95     is the time that (relative) timers are based on, and refering to it is
96     usually faster then calling EV::time.
97    
98     =item $method = EV::ev_method
99    
100     Returns an integer describing the backend used by libev (EV::METHOD_SELECT
101     or EV::METHOD_EPOLL).
102    
103     =item EV::loop [$flags]
104 root 1.2
105 root 1.20 Begin checking for events and calling callbacks. It returns when a
106     callback calls EV::loop_done.
107 root 1.2
108 root 1.20 The $flags argument can be one of the following:
109 root 1.2
110 root 1.20 0 as above
111     EV::LOOP_ONESHOT block at most once (wait, but do not loop)
112     EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
113 root 1.2
114 root 1.20 =item EV::loop_done [$how]
115 root 1.2
116 root 1.20 When called with no arguments or an argument of 1, makes the innermost
117     call to EV::loop return.
118 root 1.2
119 root 1.20 When called with an agrument of 2, all calls to EV::loop will return as
120     fast as possible.
121 root 1.2
122 root 1.20 =back
123    
124     =head2 WATCHER
125 root 1.2
126 root 1.20 A watcher is an object that gets created to record your interest in some
127     event. For instance, if you want to wait for STDIN to become readable, you
128     would create an EV::io watcher for that:
129    
130     my $watcher = EV::io *STDIN, EV::READ, sub {
131     my ($watcher, $revents) = @_;
132     warn "yeah, STDIN should not be readable without blocking!\n"
133     };
134 root 1.2
135 root 1.20 All watchers can be active (waiting for events) or inactive (paused). Only
136     active watchers will have their callbacks invoked. All callbacks will be
137     called with at least two arguments: the watcher and a bitmask of received
138     events.
139    
140     Each watcher type has its associated bit in revents, so you can use the
141     same callback for multiple watchers. The event mask is named after the
142     type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
143     EV::periodic sets EV::PERIODIC and so on, with the exception of IO events
144     (which can set both EV::READ and EV::WRITE bits), and EV::timer (which
145     uses EV::TIMEOUT).
146    
147     In the rare case where one wants to create a watcher but not start it at
148     the same time, each constructor has a variant with a trailing C<_ns> in
149     its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
150    
151     Please note that a watcher will automatically be stopped when the watcher
152 root 1.23 object is destroyed, so you I<need> to keep the watcher objects returned by
153 root 1.20 the constructors.
154    
155 root 1.23 Also, all methods changing some aspect of a watcher (->set, ->priority,
156     ->fh and so on) automatically stop and start it again if it is active,
157     which means pending events get lost.
158    
159 root 1.20 =head2 WATCHER TYPES
160    
161     Now lets move to the existing watcher types and asociated methods.
162    
163     The following methods are available for all watchers. Then followes a
164     description of each watcher constructor (EV::io, EV::timer, EV::periodic,
165     EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
166     any type-specific methods (if any).
167    
168     =over 4
169 root 1.2
170 root 1.20 =item $w->start
171    
172     Starts a watcher if it isn't active already. Does nothing to an already
173     active watcher. By default, all watchers start out in the active state
174     (see the description of the C<_ns> variants if you need stopped watchers).
175    
176     =item $w->stop
177 root 1.2
178 root 1.20 Stop a watcher if it is active. Also clear any pending events (events that
179     have been received but that didn't yet result in a callback invocation),
180     regardless of wether the watcher was active or not.
181 root 1.2
182 root 1.20 =item $bool = $w->is_active
183 root 1.2
184 root 1.20 Returns true if the watcher is active, false otherwise.
185    
186 root 1.30 =item $current_data = $w->data
187    
188     =item $old_data = $w->data ($new_data)
189    
190     Queries a freely usable data scalar on the watcher and optionally changes
191     it. This is a way to associate custom data with a watcher:
192    
193     my $w = EV::timer 60, 0, sub {
194     warn $_[0]->data;
195     };
196     $w->data ("print me!");
197    
198 root 1.20 =item $current_cb = $w->cb
199    
200     =item $old_cb = $w->cb ($new_cb)
201    
202 root 1.23 Queries the callback on the watcher and optionally changes it. You can do
203     this at any time without the watcher restarting.
204    
205     =item $current_priority = $w->priority
206    
207     =item $old_priority = $w->priority ($new_priority)
208    
209     Queries the priority on the watcher and optionally changes it. Pending
210     watchers with higher priority will be invoked first. The valid range of
211 root 1.24 priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
212     -2). If the priority is outside this range it will automatically be
213 root 1.23 normalised to the nearest valid priority.
214    
215     The default priority of any newly-created weatcher is 0.
216 root 1.20
217     =item $w->trigger ($revents)
218    
219     Call the callback *now* with the given event mask.
220    
221    
222     =item $w = EV::io $fileno_or_fh, $eventmask, $callback
223 root 1.2
224 root 1.20 =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
225 root 1.7
226 root 1.20 As long as the returned watcher object is alive, call the C<$callback>
227     when the events specified in C<$eventmask>.
228 root 1.2
229 root 1.20 The $eventmask can be one or more of these constants ORed together:
230 root 1.2
231     EV::READ wait until read() wouldn't block anymore
232     EV::WRITE wait until write() wouldn't block anymore
233 root 1.7
234 root 1.20 The C<io_ns> variant doesn't start (activate) the newly created watcher.
235 root 1.2
236 root 1.20 =item $w->set ($fileno_or_fh, $eventmask)
237 root 1.10
238 root 1.20 Reconfigures the watcher, see the constructor above for details. Can be
239     called at any time.
240 root 1.10
241 root 1.20 =item $current_fh = $w->fh
242    
243     =item $old_fh = $w->fh ($new_fh)
244    
245     Returns the previously set filehandle and optionally set a new one.
246 root 1.10
247 root 1.20 =item $current_eventmask = $w->events
248    
249     =item $old_eventmask = $w->events ($new_eventmask)
250 root 1.10
251 root 1.20 Returns the previously set event mask and optionally set a new one.
252 root 1.10
253    
254 root 1.20 =item $w = EV::timer $after, $repeat, $callback
255 root 1.2
256 root 1.20 =item $w = EV::timer_ns $after, $repeat, $callback
257 root 1.2
258 root 1.20 Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
259     the timer will be restarted (with the $repeat value as $after) after the
260     callback returns.
261 root 1.2
262 root 1.20 This means that the callback would be called roughly after C<$after>
263     seconds, and then every C<$repeat> seconds. "Roughly" because the time of
264     callback processing is not taken into account, so the timer will slowly
265     drift. If that isn't acceptable, look at EV::periodic.
266 root 1.2
267 root 1.20 The timer is based on a monotonic clock, that is if somebody is sitting
268     in front of the machine while the timer is running and changes the system
269     clock, the timer will nevertheless run (roughly) the same time.
270 root 1.2
271 root 1.20 The C<timer_ns> variant doesn't start (activate) the newly created watcher.
272    
273     =item $w->set ($after, $repeat)
274    
275     Reconfigures the watcher, see the constructor above for details. Can be at
276     any time.
277    
278     =item $w->again
279    
280     Similar to the C<start> method, but has special semantics for repeating timers:
281    
282     If the timer is active and repeating, reset the timeout to occur
283     C<$repeat> seconds after now.
284    
285     If the timer is active and non-repeating, it will be stopped.
286    
287     If the timer is in active and repeating, start it.
288    
289     Otherwise do nothing.
290    
291     This behaviour is useful when you have a timeout for some IO
292     operation. You create a timer object with the same value for C<$after> and
293     C<$repeat>, and then, in the read/write watcher, run the C<again> method
294     on the timeout.
295    
296    
297 root 1.30 =item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
298 root 1.20
299 root 1.30 =item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
300    
301     Similar to EV::timer, but is not based on relative timeouts but on
302     absolute times. Apart from creating "simple" timers that trigger "at" the
303     specified time, it can also be used for non-drifting absolute timers and
304     more complex, cron-like, setups that are not adversely affected by time
305     jumps (i.e. when the system clock is changed by explicit date -s or other
306     means such as ntpd). It is also the most complex watcher type in EV.
307    
308     It has three distinct "modes":
309    
310     =over 4
311 root 1.2
312 root 1.30 =item * absolute timer ($interval = $reschedule_cb = 0)
313 root 1.2
314 root 1.30 This time simply fires at the wallclock time C<$at> and doesn't repeat. It
315     will not adjust when a time jump occurs, that is, if it is to be run
316     at January 1st 2011 then it will run when the system time reaches or
317     surpasses this time.
318 root 1.2
319 root 1.30 =item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
320 root 1.2
321 root 1.30 In this mode the watcher will always be scheduled to time out at the
322     next C<$at + N * $interval> time (for some integer N) and then repeat,
323     regardless of any time jumps.
324    
325     This can be used to create timers that do not drift with respect to system
326     time:
327    
328     my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
329    
330     That doesn't mean there will always be 3600 seconds in between triggers,
331     but only that the the clalback will be called when the system time shows a
332     full hour (UTC).
333 root 1.2
334 root 1.7 Another way to think about it (for the mathematically inclined) is that
335 root 1.30 EV::periodic will try to run the callback in this mode at the next
336     possible time where C<$time = $at (mod $interval)>, regardless of any time
337     jumps.
338    
339     =item * manual reschedule mode ($reschedule_cb = coderef)
340    
341     In this mode $interval and $at are both being ignored. Instead, each time
342     the periodic watcher gets scheduled, the first callback ($reschedule_cb)
343     will be called with the watcher as first, and the current time as second
344     argument.
345    
346 root 1.31 I<This callback MUST NOT stop or destroy this or any other periodic
347     watcher, ever>. If you need to stop it, return 1e30 and stop it
348     afterwards.
349 root 1.30
350     It must return the next time to trigger, based on the passed time value
351     (that is, the lowest time value larger than to the second argument). It
352     will usually be called just before the callback will be triggered, but
353     might be called at other times, too.
354    
355     This can be used to create very complex timers, such as a timer that
356     triggers on each midnight, local time (actually 24 hours after the last
357     midnight, to keep the example simple. If you know a way to do it correctly
358     in about the same space (without requiring elaborate modules), drop me a
359     note :):
360    
361     my $daily = EV::periodic 0, 0, sub {
362     my ($w, $now) = @_;
363    
364     use Time::Local ();
365     my (undef, undef, undef, $d, $m, $y) = localtime $now;
366     86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
367     }, sub {
368     print "it's midnight or likely shortly after, now\n";
369     };
370 root 1.7
371 root 1.30 =back
372 root 1.20
373     The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
374 root 1.2
375 root 1.30 =item $w->set ($at, $interval, $reschedule_cb)
376 root 1.11
377 root 1.20 Reconfigures the watcher, see the constructor above for details. Can be at
378     any time.
379    
380 root 1.30 =item $w->again
381    
382     Simply stops and starts the watcher again.
383    
384 root 1.20
385     =item $w = EV::signal $signal, $callback
386    
387     =item $w = EV::signal_ns $signal, $callback
388 root 1.11
389     Call the callback when $signal is received (the signal can be specified
390 root 1.20 by number or by name, just as with kill or %SIG).
391 root 1.2
392 root 1.11 EV will grab the signal for the process (the kernel only allows one
393 root 1.20 component to receive a signal at a time) when you start a signal watcher,
394     and removes it again when you stop it. Perl does the same when you
395     add/remove callbacks to %SIG, so watch out.
396    
397     You can have as many signal watchers per signal as you want.
398 root 1.2
399 root 1.20 The C<signal_ns> variant doesn't start (activate) the newly created watcher.
400 root 1.2
401 root 1.20 =item $w->set ($signal)
402 root 1.2
403 root 1.20 Reconfigures the watcher, see the constructor above for details. Can be at
404     any time.
405    
406 root 1.22 =item $current_signum = $w->signal
407    
408     =item $old_signum = $w->signal ($new_signal)
409    
410     Returns the previously set signal (always as a number not name) and
411     optionally set a new one.
412    
413 root 1.20
414     =item $w = EV::child $pid, $callback
415    
416     =item $w = EV::child_ns $pid, $callback
417    
418     Call the callback when a status change for pid C<$pid> (or any pid
419     if C<$pid> is 0) has been received. More precisely: when the process
420     receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
421     changed/zombie children and call the callback.
422    
423 root 1.27 You can access both status and pid by using the C<rstatus> and C<rpid>
424     methods on the watcher object.
425 root 1.20
426     You can have as many pid watchers per pid as you want.
427    
428     The C<child_ns> variant doesn't start (activate) the newly created watcher.
429    
430     =item $w->set ($pid)
431 root 1.1
432 root 1.20 Reconfigures the watcher, see the constructor above for details. Can be at
433     any time.
434 root 1.2
435 root 1.22 =item $current_pid = $w->pid
436    
437     =item $old_pid = $w->pid ($new_pid)
438    
439     Returns the previously set process id and optionally set a new one.
440    
441 root 1.27 =item $exit_status = $w->rstatus
442    
443     Return the exit/wait status (as returned by waitpid, see the waitpid entry
444     in perlfunc).
445    
446     =item $pid = $w->rpid
447    
448     Return the pid of the awaited child (useful when you have installed a
449     watcher for all pids).
450    
451 root 1.2
452 root 1.20 =item $w = EV::idle $callback
453 root 1.2
454 root 1.20 =item $w = EV::idle_ns $callback
455 root 1.2
456 root 1.20 Call the callback when there are no pending io, timer/periodic, signal or
457     child events, i.e. when the process is idle.
458 root 1.2
459 root 1.20 The process will not block as long as any idle watchers are active, and
460     they will be called repeatedly until stopped.
461 root 1.2
462 root 1.20 The C<idle_ns> variant doesn't start (activate) the newly created watcher.
463 root 1.2
464    
465 root 1.20 =item $w = EV::prepare $callback
466 root 1.1
467 root 1.20 =item $w = EV::prepare_ns $callback
468 root 1.1
469 root 1.20 Call the callback just before the process would block. You can still
470     create/modify any watchers at this point.
471 root 1.1
472 root 1.20 See the EV::check watcher, below, for explanations and an example.
473 root 1.2
474 root 1.20 The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
475 root 1.2
476    
477 root 1.20 =item $w = EV::check $callback
478 root 1.2
479 root 1.20 =item $w = EV::check_ns $callback
480 root 1.10
481 root 1.20 Call the callback just after the process wakes up again (after it has
482     gathered events), but before any other callbacks have been invoked.
483 root 1.10
484 root 1.20 This is used to integrate other event-based software into the EV
485     mainloop: You register a prepare callback and in there, you create io and
486     timer watchers as required by the other software. Here is a real-world
487     example of integrating Net::SNMP (with some details left out):
488 root 1.10
489 root 1.20 our @snmp_watcher;
490 root 1.2
491 root 1.20 our $snmp_prepare = EV::prepare sub {
492     # do nothing unless active
493     $dispatcher->{_event_queue_h}
494     or return;
495 root 1.2
496 root 1.20 # make the dispatcher handle any outstanding stuff
497 root 1.2
498 root 1.20 # create an IO watcher for each and every socket
499     @snmp_watcher = (
500     (map { EV::io $_, EV::READ, sub { } }
501     keys %{ $dispatcher->{_descriptors} }),
502     );
503 root 1.2
504 root 1.20 # if there are any timeouts, also create a timer
505     push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
506     if $event->[Net::SNMP::Dispatcher::_ACTIVE];
507     };
508 root 1.2
509 root 1.20 The callbacks are irrelevant, the only purpose of those watchers is
510     to wake up the process as soon as one of those events occurs (socket
511     readable, or timer timed out). The corresponding EV::check watcher will then
512     clean up:
513 root 1.2
514 root 1.20 our $snmp_check = EV::check sub {
515     # destroy all watchers
516     @snmp_watcher = ();
517 root 1.2
518 root 1.20 # make the dispatcher handle any new stuff
519     };
520 root 1.2
521 root 1.20 The callbacks of the created watchers will not be called as the watchers
522     are destroyed before this cna happen (remember EV::check gets called
523     first).
524 root 1.2
525 root 1.20 The C<check_ns> variant doesn't start (activate) the newly created watcher.
526 root 1.1
527     =back
528    
529 root 1.13 =head1 THREADS
530    
531     Threads are not supported by this in any way. Perl pseudo-threads is evil
532 root 1.20 stuff and must die.
533 root 1.13
534 root 1.1 =cut
535    
536 root 1.8 our $DIED = sub {
537     warn "EV: error in callback (ignoring): $@";
538     };
539    
540 root 1.28 default_loop
541 root 1.26 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
542 root 1.1
543     1;
544    
545 root 1.3 =head1 SEE ALSO
546    
547 root 1.20 L<EV::DNS>, L<EV::AnyEvent>.
548 root 1.3
549 root 1.1 =head1 AUTHOR
550    
551     Marc Lehmann <schmorp@schmorp.de>
552     http://home.schmorp.de/
553    
554     =cut
555