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

Comparing EV/EV.pm (file contents):
Revision 1.18 by root, Thu Nov 1 08:10:03 2007 UTC vs.
Revision 1.27 by root, Sat Nov 3 09:19:58 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 {
… …
56 }; 40 };
57 41
58 # CHILD/PID STATUS CHANGES 42 # CHILD/PID STATUS CHANGES
59 43
60 my $w = EV::child 666, sub { 44 my $w = EV::child 666, sub {
61 my ($w, $revents, $status) = @_; 45 my ($w, $revents) = @_;
46 # my $pid = $w->rpid;
47 my $status = $w->rstatus;
62 }; 48 };
63 49
64 # MAINLOOP 50 # MAINLOOP
65 EV::dispatch; # loop as long as watchers are active 51 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 52 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 53 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
69 54
70=head1 DESCRIPTION 55=head1 DESCRIPTION
71 56
72This module provides an interface to libev 57This module provides an interface to libev
73(L<http://software.schmorp.de/pkg/libev.html>). You probably should 58(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 59
77=cut 60=cut
78 61
79package EV; 62package EV;
80 63
81use strict; 64use strict;
82 65
83BEGIN { 66BEGIN {
84 our $VERSION = '0.03'; 67 our $VERSION = '0.5';
85 use XSLoader; 68 use XSLoader;
86 XSLoader::load "EV", $VERSION; 69 XSLoader::load "EV", $VERSION;
87} 70}
88 71
89@EV::Io::ISA = 72@EV::Io::ISA =
… …
97 80
98=head1 BASIC INTERFACE 81=head1 BASIC INTERFACE
99 82
100=over 4 83=over 4
101 84
102=item $EV::NPRI
103
104How many priority levels are available.
105
106=item $EV::DIED 85=item $EV::DIED
107 86
108Must contain a reference to a function that is called when a callback 87Must contain a reference to a function that is called when a callback
109throws an exception (with $@ containing thr error). The default prints an 88throws an exception (with $@ containing thr error). The default prints an
110informative message and continues. 89informative message and continues.
111 90
112If this callback throws an exception it will be silently ignored. 91If this callback throws an exception it will be silently ignored.
113 92
93=item $time = EV::time
94
95Returns the current time in (fractional) seconds since the epoch.
96
114=item $time = EV::now 97=item $time = EV::now
115 98
116Returns the time in (fractional) seconds since the epoch. 99Returns the time the last event loop iteration has been started. This
100is the time that (relative) timers are based on, and refering to it is
101usually faster then calling EV::time.
117 102
118=item $version = EV::version
119
120=item $method = EV::method 103=item $method = EV::ev_method
121 104
122Return version string and event polling method used. 105Returns an integer describing the backend used by libev (EV::METHOD_SELECT
106or EV::METHOD_EPOLL).
123 107
124=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT 108=item EV::loop [$flags]
125 109
126=item EV::loopexit $after 110Begin checking for events and calling callbacks. It returns when a
111callback calls EV::loop_done.
127 112
128Exit any active loop or dispatch after C<$after> seconds or immediately if 113The $flags argument can be one of the following:
129C<$after> is missing or zero.
130 114
131=item EV::dispatch 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)
132 118
133Same as C<EV::loop 0>. 119=item EV::loop_done [$how]
134 120
135=item EV::event $callback 121When called with no arguments or an argument of 1, makes the innermost
122call to EV::loop return.
136 123
137Creates a new event watcher waiting for nothing, calling the given callback. 124When called with an agrument of 2, all calls to EV::loop will return as
125fast as possible.
138 126
127=back
128
129=head2 WATCHER
130
131A watcher is an object that gets created to record your interest in some
132event. For instance, if you want to wait for STDIN to become readable, you
133would 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
140All watchers can be active (waiting for events) or inactive (paused). Only
141active watchers will have their callbacks invoked. All callbacks will be
142called with at least two arguments: the watcher and a bitmask of received
143events.
144
145Each watcher type has its associated bit in revents, so you can use the
146same callback for multiple watchers. The event mask is named after the
147type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
148EV::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
150uses EV::TIMEOUT).
151
152In the rare case where one wants to create a watcher but not start it at
153the same time, each constructor has a variant with a trailing C<_ns> in
154its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
155
156Please note that a watcher will automatically be stopped when the watcher
157object is destroyed, so you I<need> to keep the watcher objects returned by
158the constructors.
159
160Also, 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,
162which means pending events get lost.
163
164=head2 WATCHER TYPES
165
166Now lets move to the existing watcher types and asociated methods.
167
168The following methods are available for all watchers. Then followes a
169description of each watcher constructor (EV::io, EV::timer, EV::periodic,
170EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
171any type-specific methods (if any).
172
173=over 4
174
175=item $w->start
176
177Starts a watcher if it isn't active already. Does nothing to an already
178active 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
183Stop a watcher if it is active. Also clear any pending events (events that
184have been received but that didn't yet result in a callback invocation),
185regardless of wether the watcher was active or not.
186
187=item $bool = $w->is_active
188
189Returns true if the watcher is active, false otherwise.
190
191=item $current_cb = $w->cb
192
193=item $old_cb = $w->cb ($new_cb)
194
195Queries the callback on the watcher and optionally changes it. You can do
196this at any time without the watcher restarting.
197
198=item $current_priority = $w->priority
199
200=item $old_priority = $w->priority ($new_priority)
201
202Queries the priority on the watcher and optionally changes it. Pending
203watchers with higher priority will be invoked first. The valid range of
204priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
205-2). If the priority is outside this range it will automatically be
206normalised to the nearest valid priority.
207
208The default priority of any newly-created weatcher is 0.
209
210=item $w->trigger ($revents)
211
212Call the callback *now* with the given event mask.
213
214
139=item my $w = EV::io $fileno_or_fh, $eventmask, $callback 215=item $w = EV::io $fileno_or_fh, $eventmask, $callback
140 216
141=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 217=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
142 218
143As long as the returned watcher object is alive, call the C<$callback> 219As long as the returned watcher object is alive, call the C<$callback>
144when the events specified in C<$eventmask> happen. Initially, the timeout 220when the events specified in C<$eventmask>.
145is disabled.
146 221
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: 222The $eventmask can be one or more of these constants ORed together:
156 223
157 EV::READ wait until read() wouldn't block anymore 224 EV::READ wait until read() wouldn't block anymore
158 EV::WRITE wait until write() wouldn't block anymore 225 EV::WRITE wait until write() wouldn't block anymore
159 EV::PERSIST stay active after a (non-timeout) event occured
160 226
161The C<io_ns> variant doesn't add/start the newly created watcher. 227The C<io_ns> variant doesn't start (activate) the newly created watcher.
162 228
163=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback 229=item $w->set ($fileno_or_fh, $eventmask)
164 230
165=item my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback 231Reconfigures the watcher, see the constructor above for details. Can be
232called at any time.
166 233
167Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was 234=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 235
171If the timeout is zero or undef, no timeout will be set, and a normal 236=item $old_fh = $w->fh ($new_fh)
172watcher (with the persist flag set!) will be created.
173 237
174This has the effect of timing out after the specified period of inactivity 238Returns the previously set filehandle and optionally set a new one.
175has happened.
176 239
177Due to the design of libevent, this is also relatively inefficient, having 240=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 241
242=item $old_eventmask = $w->events ($new_eventmask)
243
244Returns the previously set event mask and optionally set a new one.
245
246
181=item my $w = EV::timer $after, $repeat, $callback 247=item $w = EV::timer $after, $repeat, $callback
182 248
183=item my $w = EV::timer_ns $after, $repeat, $callback 249=item $w = EV::timer_ns $after, $repeat, $callback
184 250
185Calls the callback after C<$after> seconds. If C<$repeat> is true, the 251Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
186timer will be restarted after the callback returns. This means that the 252the timer will be restarted (with the $repeat value as $after) after the
187callback would be called roughly every C<$after> seconds, prolonged by the 253callback returns.
188time the callback takes.
189 254
255This means that the callback would be called roughly after C<$after>
256seconds, and then every C<$repeat> seconds. "Roughly" because the time of
257callback processing is not taken into account, so the timer will slowly
258drift. If that isn't acceptable, look at EV::periodic.
259
260The timer is based on a monotonic clock, that is if somebody is sitting
261in front of the machine while the timer is running and changes the system
262clock, the timer will nevertheless run (roughly) the same time.
263
190The C<timer_ns> variant doesn't add/start the newly created watcher. 264The C<timer_ns> variant doesn't start (activate) the newly created watcher.
191 265
266=item $w->set ($after, $repeat)
267
268Reconfigures the watcher, see the constructor above for details. Can be at
269any time.
270
271=item $w->again
272
273Similar to the C<start> method, but has special semantics for repeating timers:
274
275If the timer is active and repeating, reset the timeout to occur
276C<$repeat> seconds after now.
277
278If the timer is active and non-repeating, it will be stopped.
279
280If the timer is in active and repeating, start it.
281
282Otherwise do nothing.
283
284This behaviour is useful when you have a timeout for some IO
285operation. You create a timer object with the same value for C<$after> and
286C<$repeat>, and then, in the read/write watcher, run the C<again> method
287on the timeout.
288
289
290=item $w = EV::periodic $at, $interval, $callback
291
192=item my $w = EV::timer_abs $at, $interval, $callback 292=item $w = EV::periodic_ns $at, $interval, $callback
193
194=item my $w = EV::timer_abs_ns $at, $interval, $callback
195 293
196Similar to EV::timer, but the time is given as an absolute point in time 294Similar to EV::timer, but the time is given as an absolute point in time
197(C<$at>), plus an optional C<$interval>. 295(C<$at>), plus an optional C<$interval>.
198 296
199If the C<$interval> is zero, then the callback will be called at the time 297If 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 298C<$at> if that is in the future, or as soon as possible if it is in the
201past. It will not automatically repeat. 299past. It will not automatically repeat.
202 300
203If the C<$interval> is nonzero, then the watcher will always be scheduled 301If the C<$interval> is nonzero, then the watcher will always be scheduled
204to time out at the next C<$at + integer * $interval> time. 302to time out at the next C<$at + N * $interval> time.
205 303
206This can be used to schedule a callback to run at very regular intervals, 304This 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 305as long as the processing time is less then the interval (otherwise
208obviously events will be skipped). 306obviously events will be skipped).
209 307
210Another way to think about it (for the mathematically inclined) is that 308Another 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 309EV::periodic will try to run the callback at the next possible time where
212C<$time = $at (mod $interval)>, regardless of any time jumps. 310C<$time = $at (mod $interval)>, regardless of any time jumps.
213 311
312This periodic timer is based on "wallclock time", that is, if the clock
313changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
314the specified time. This means it will never drift (it might jitter, but
315it will not drift).
316
214The C<timer_abs_ns> variant doesn't add/start the newly created watcher. 317The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
215 318
319=item $w->set ($at, $interval)
320
321Reconfigures the watcher, see the constructor above for details. Can be at
322any time.
323
324
216=item my $w = EV::signal $signal, $callback 325=item $w = EV::signal $signal, $callback
217 326
218=item my $w = EV::signal_ns $signal, $callback 327=item $w = EV::signal_ns $signal, $callback
219 328
220Call the callback when $signal is received (the signal can be specified 329Call 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 330by number or by name, just as with kill or %SIG).
222persistent no natter what.
223 331
224EV will grab the signal for the process (the kernel only allows one 332EV will grab the signal for the process (the kernel only allows one
225component to receive signals) when you start a signal watcher, and 333component 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 334and removes it again when you stop it. Perl does the same when you
227callbacks to %SIG, so watch out. 335add/remove callbacks to %SIG, so watch out.
228 336
229Unfortunately, only one handler can be registered per signal. Screw 337You can have as many signal watchers per signal as you want.
230libevent.
231 338
232The C<signal_ns> variant doesn't add/start the newly created watcher. 339The C<signal_ns> variant doesn't start (activate) the newly created watcher.
340
341=item $w->set ($signal)
342
343Reconfigures the watcher, see the constructor above for details. Can be at
344any time.
345
346=item $current_signum = $w->signal
347
348=item $old_signum = $w->signal ($new_signal)
349
350Returns the previously set signal (always as a number not name) and
351optionally set a new one.
352
353
354=item $w = EV::child $pid, $callback
355
356=item $w = EV::child_ns $pid, $callback
357
358Call the callback when a status change for pid C<$pid> (or any pid
359if C<$pid> is 0) has been received. More precisely: when the process
360receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
361changed/zombie children and call the callback.
362
363You can access both status and pid by using the C<rstatus> and C<rpid>
364methods on the watcher object.
365
366You can have as many pid watchers per pid as you want.
367
368The C<child_ns> variant doesn't start (activate) the newly created watcher.
369
370=item $w->set ($pid)
371
372Reconfigures the watcher, see the constructor above for details. Can be at
373any time.
374
375=item $current_pid = $w->pid
376
377=item $old_pid = $w->pid ($new_pid)
378
379Returns the previously set process id and optionally set a new one.
380
381=item $exit_status = $w->rstatus
382
383Return the exit/wait status (as returned by waitpid, see the waitpid entry
384in perlfunc).
385
386=item $pid = $w->rpid
387
388Return the pid of the awaited child (useful when you have installed a
389watcher for all pids).
390
391
392=item $w = EV::idle $callback
393
394=item $w = EV::idle_ns $callback
395
396Call the callback when there are no pending io, timer/periodic, signal or
397child events, i.e. when the process is idle.
398
399The process will not block as long as any idle watchers are active, and
400they will be called repeatedly until stopped.
401
402The C<idle_ns> variant doesn't start (activate) the newly created watcher.
403
404
405=item $w = EV::prepare $callback
406
407=item $w = EV::prepare_ns $callback
408
409Call the callback just before the process would block. You can still
410create/modify any watchers at this point.
411
412See the EV::check watcher, below, for explanations and an example.
413
414The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
415
416
417=item $w = EV::check $callback
418
419=item $w = EV::check_ns $callback
420
421Call the callback just after the process wakes up again (after it has
422gathered events), but before any other callbacks have been invoked.
423
424This is used to integrate other event-based software into the EV
425mainloop: You register a prepare callback and in there, you create io and
426timer watchers as required by the other software. Here is a real-world
427example of integrating Net::SNMP (with some details left out):
428
429 our @snmp_watcher;
430
431 our $snmp_prepare = EV::prepare sub {
432 # do nothing unless active
433 $dispatcher->{_event_queue_h}
434 or return;
435
436 # make the dispatcher handle any outstanding stuff
437
438 # create an IO watcher for each and every socket
439 @snmp_watcher = (
440 (map { EV::io $_, EV::READ, sub { } }
441 keys %{ $dispatcher->{_descriptors} }),
442 );
443
444 # if there are any timeouts, also create a timer
445 push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
446 if $event->[Net::SNMP::Dispatcher::_ACTIVE];
447 };
448
449The callbacks are irrelevant, the only purpose of those watchers is
450to wake up the process as soon as one of those events occurs (socket
451readable, or timer timed out). The corresponding EV::check watcher will then
452clean up:
453
454 our $snmp_check = EV::check sub {
455 # destroy all watchers
456 @snmp_watcher = ();
457
458 # make the dispatcher handle any new stuff
459 };
460
461The callbacks of the created watchers will not be called as the watchers
462are destroyed before this cna happen (remember EV::check gets called
463first).
464
465The C<check_ns> variant doesn't start (activate) the newly created watcher.
233 466
234=back 467=back
235 468
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 469=head1 THREADS
299 470
300Threads are not supported by this in any way. Perl pseudo-threads is evil 471Threads are not supported by this in any way. Perl pseudo-threads is evil
301and must die. 472stuff and must die.
302 473
303=cut 474=cut
304 475
305our $DIED = sub { 476our $DIED = sub {
306 warn "EV: error in callback (ignoring): $@"; 477 warn "EV: error in callback (ignoring): $@";
307}; 478};
308 479
309init; 480init
481 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
310 482
311push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"]; 483push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
312 484
3131; 4851;
314 486
315=head1 SEE ALSO 487=head1 SEE ALSO
316 488
317 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
318 L<EV::AnyEvent>. 489 L<EV::DNS>, L<EV::AnyEvent>.
319 490
320=head1 AUTHOR 491=head1 AUTHOR
321 492
322 Marc Lehmann <schmorp@schmorp.de> 493 Marc Lehmann <schmorp@schmorp.de>
323 http://home.schmorp.de/ 494 http://home.schmorp.de/

Diff Legend

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