ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
Revision: 1.30
Committed: Thu Nov 8 02:19:36 2007 UTC (16 years, 6 months ago) by root
Branch: MAIN
Changes since 1.29: +83 -20 lines
Log Message:
*** empty log message ***

File Contents

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