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

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines