ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
Revision: 1.35
Committed: Sat Nov 10 05:31:48 2007 UTC (16 years, 6 months ago) by root
Branch: MAIN
Changes since 1.34: +4 -9 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, 2, sub {
16 warn "is called roughly every 2s (repeat = 2)";
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 receive the watcher 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 # CHILD/PID STATUS CHANGES
39
40 my $w = EV::child 666, sub {
41 my ($w, $revents) = @_;
42 my $status = $w->rstatus;
43 };
44
45 # MAINLOOP
46 EV::loop; # loop until EV::loop_done is called or all watchers stop
47 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
50 =head1 DESCRIPTION
51
52 This module provides an interface to libev
53 (L<http://software.schmorp.de/pkg/libev.html>).
54
55 =cut
56
57 package EV;
58
59 use strict;
60
61 BEGIN {
62 our $VERSION = '0.7';
63 use XSLoader;
64 XSLoader::load "EV", $VERSION;
65 }
66
67 @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 @EV::Child::ISA = "EV::Watcher";
75
76 =head1 BASIC INTERFACE
77
78 =over 4
79
80 =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 =item $time = EV::time
89
90 Returns the current time in (fractional) seconds since the epoch.
91
92 =item $time = EV::now
93
94 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
105 Begin checking for events and calling callbacks. It returns when a
106 callback calls EV::loop_done.
107
108 The $flags argument can be one of the following:
109
110 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
114 =item EV::loop_done [$how]
115
116 When called with no arguments or an argument of 1, makes the innermost
117 call to EV::loop return.
118
119 When called with an agrument of 2, all calls to EV::loop will return as
120 fast as possible.
121
122 =back
123
124 =head2 WATCHER
125
126 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
135 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 object is destroyed, so you I<need> to keep the watcher objects returned by
153 the constructors.
154
155 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 =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
170 =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
178 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
182 =item $bool = $w->is_active
183
184 Returns true if the watcher is active, false otherwise.
185
186 =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 =item $current_cb = $w->cb
199
200 =item $old_cb = $w->cb ($new_cb)
201
202 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 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 normalised to the nearest valid priority.
214
215 The default priority of any newly-created weatcher is 0.
216
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
224 =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
225
226 As long as the returned watcher object is alive, call the C<$callback>
227 when the events specified in C<$eventmask>.
228
229 The $eventmask can be one or more of these constants ORed together:
230
231 EV::READ wait until read() wouldn't block anymore
232 EV::WRITE wait until write() wouldn't block anymore
233
234 The C<io_ns> variant doesn't start (activate) the newly created watcher.
235
236 =item $w->set ($fileno_or_fh, $eventmask)
237
238 Reconfigures the watcher, see the constructor above for details. Can be
239 called at any time.
240
241 =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
247 =item $current_eventmask = $w->events
248
249 =item $old_eventmask = $w->events ($new_eventmask)
250
251 Returns the previously set event mask and optionally set a new one.
252
253
254 =item $w = EV::timer $after, $repeat, $callback
255
256 =item $w = EV::timer_ns $after, $repeat, $callback
257
258 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
262 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
267 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
271 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 =item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
298
299 =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
312 =item * absolute timer ($interval = $reschedule_cb = 0)
313
314 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
319 =item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
320
321 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
334 Another way to think about it (for the mathematically inclined) is that
335 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 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
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
371 =back
372
373 The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
374
375 =item $w->set ($at, $interval, $reschedule_cb)
376
377 Reconfigures the watcher, see the constructor above for details. Can be at
378 any time.
379
380 =item $w->again
381
382 Simply stops and starts the watcher again.
383
384
385 =item $w = EV::signal $signal, $callback
386
387 =item $w = EV::signal_ns $signal, $callback
388
389 Call the callback when $signal is received (the signal can be specified
390 by number or by name, just as with kill or %SIG).
391
392 EV will grab the signal for the process (the kernel only allows one
393 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
399 The C<signal_ns> variant doesn't start (activate) the newly created watcher.
400
401 =item $w->set ($signal)
402
403 Reconfigures the watcher, see the constructor above for details. Can be at
404 any time.
405
406 =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
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 You can access both status and pid by using the C<rstatus> and C<rpid>
424 methods on the watcher object.
425
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
432 Reconfigures the watcher, see the constructor above for details. Can be at
433 any time.
434
435 =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 =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
452 =item $w = EV::idle $callback
453
454 =item $w = EV::idle_ns $callback
455
456 Call the callback when there are no pending io, timer/periodic, signal or
457 child events, i.e. when the process is idle.
458
459 The process will not block as long as any idle watchers are active, and
460 they will be called repeatedly until stopped.
461
462 The C<idle_ns> variant doesn't start (activate) the newly created watcher.
463
464
465 =item $w = EV::prepare $callback
466
467 =item $w = EV::prepare_ns $callback
468
469 Call the callback just before the process would block. You can still
470 create/modify any watchers at this point.
471
472 See the EV::check watcher, below, for explanations and an example.
473
474 The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
475
476
477 =item $w = EV::check $callback
478
479 =item $w = EV::check_ns $callback
480
481 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
484 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
489 our @snmp_watcher;
490
491 our $snmp_prepare = EV::prepare sub {
492 # do nothing unless active
493 $dispatcher->{_event_queue_h}
494 or return;
495
496 # make the dispatcher handle any outstanding stuff
497
498 # 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
504 # 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
509 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
514 our $snmp_check = EV::check sub {
515 # destroy all watchers
516 @snmp_watcher = ();
517
518 # make the dispatcher handle any new stuff
519 };
520
521 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
525 The C<check_ns> variant doesn't start (activate) the newly created watcher.
526
527 =back
528
529 =head1 THREADS
530
531 Threads are not supported by this in any way. Perl pseudo-threads is evil
532 stuff and must die.
533
534 =cut
535
536 our $DIED = sub {
537 warn "EV: error in callback (ignoring): $@";
538 };
539
540 default_loop
541 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
542
543 1;
544
545 =head1 SEE ALSO
546
547 L<EV::DNS>, L<EV::AnyEvent>.
548
549 =head1 AUTHOR
550
551 Marc Lehmann <schmorp@schmorp.de>
552 http://home.schmorp.de/
553
554 =cut
555