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

Comparing EV/EV.pm (file contents):
Revision 1.10 by root, Mon Oct 29 07:24:37 2007 UTC vs.
Revision 1.29 by root, Tue Nov 6 17:20:42 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, 1, sub {
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 # IO
22
23 my $w = EV::timer_abs 0, 60, sub { 21 my $w = EV::periodic 0, 60, 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 get the watcher object and event mask
29 if ($events & 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 }; 30 };
35 $w->timeout (10); 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 };
36 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
37 # MAINLOOP 50 # MAINLOOP
38 EV::dispatch; # loop as long as watchers are active 51 EV::loop; # loop until EV::loop_done is called
39 EV::loop; # the same thing 52 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
40 EV::loop EV::LOOP_ONCE; 53 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
41 EV::loop EV::LOOP_ONSHOT;
42 54
43=head1 DESCRIPTION 55=head1 DESCRIPTION
44 56
45This module provides an interface to libevent 57This module provides an interface to libev
46(L<http://monkey.org/~provos/libevent/>). You probably should acquaint 58(L<http://software.schmorp.de/pkg/libev.html>).
47yourself with its documentation and source code to be able to use this
48module fully.
49
50Please note thta this module disables the libevent EPOLL method by
51default, see BUGS, below, if you need to enable it.
52 59
53=cut 60=cut
54 61
55package EV; 62package EV;
56 63
57use strict; 64use strict;
58 65
59BEGIN { 66BEGIN {
60 our $VERSION = '0.02'; 67 our $VERSION = '0.51';
61 use XSLoader; 68 use XSLoader;
62 XSLoader::load "EV", $VERSION; 69 XSLoader::load "EV", $VERSION;
63} 70}
64 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
65=head1 BASIC INTERFACE 81=head1 BASIC INTERFACE
66 82
67=over 4 83=over 4
68
69=item $EV::NPRI
70
71How many priority levels are available.
72 84
73=item $EV::DIED 85=item $EV::DIED
74 86
75Must 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
76throws an exception (with $@ containing thr error). The default prints an 88throws an exception (with $@ containing thr error). The default prints an
77informative message and continues. 89informative message and continues.
78 90
79If this callback throws an exception it will be silently ignored. 91If this callback throws an exception it will be silently ignored.
80 92
93=item $time = EV::time
94
95Returns the current time in (fractional) seconds since the epoch.
96
81=item $time = EV::now 97=item $time = EV::now
82 98
83Returns 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.
84 102
85=item $version = EV::version
86
87=item $method = EV::method 103=item $method = EV::ev_method
88 104
89Return version string and event polling method used. 105Returns an integer describing the backend used by libev (EV::METHOD_SELECT
106or EV::METHOD_EPOLL).
90 107
91=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT 108=item EV::loop [$flags]
92 109
93=item EV::loopexit $after 110Begin checking for events and calling callbacks. It returns when a
111callback calls EV::loop_done.
94 112
95Exit any active loop or dispatch after C<$after> seconds or immediately if 113The $flags argument can be one of the following:
96C<$after> is missing or zero.
97 114
98=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)
99 118
100Same as C<EV::loop 0>. 119=item EV::loop_done [$how]
101 120
102=item EV::event $callback 121When called with no arguments or an argument of 1, makes the innermost
122call to EV::loop return.
103 123
104Creates 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.
105 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
106=item my $w = EV::io $fileno_or_fh, $eventmask, $callback 215=item $w = EV::io $fileno_or_fh, $eventmask, $callback
107 216
108=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 217=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
109 218
110As 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>
111when the events specified in C<$eventmask> happen. Initially, the timeout 220when the events specified in C<$eventmask>.
112is disabled.
113 221
114You can additionall set a timeout to occur on the watcher, but note that
115this timeout will not be reset when you get an I/O event in the EV::PERSIST
116case, and reaching a timeout will always stop the watcher even in the
117EV::PERSIST case.
118
119If you want a timeout to occur only after a specific time of inactivity, set
120a repeating timeout and do NOT use EV::PERSIST.
121
122Eventmask can be one or more of these constants ORed together: 222The $eventmask can be one or more of these constants ORed together:
123 223
124 EV::READ wait until read() wouldn't block anymore 224 EV::READ wait until read() wouldn't block anymore
125 EV::WRITE wait until write() wouldn't block anymore 225 EV::WRITE wait until write() wouldn't block anymore
126 EV::PERSIST stay active after a (non-timeout) event occured
127 226
128The 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.
129 228
130=item my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback 229=item $w->set ($fileno_or_fh, $eventmask)
131 230
132=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.
133 233
134Same as C<io> and C<io_ns>, but also specifies a timeout (as if there was 234=item $current_fh = $w->fh
135a call to C<< $w->timeout ($timout, 1) >>. The persist flag is not allowed
136and will automatically be cleared. The watcher will be restarted after each event.
137 235
138If the timeout is zero or undef, no timeout will be set, and a normal 236=item $old_fh = $w->fh ($new_fh)
139watcher (with the persist flag set!) will be created.
140 237
141This has the effect of timing out after the specified period of inactivity 238Returns the previously set filehandle and optionally set a new one.
142has happened.
143 239
144Due to the design of libevent, this is also relatively inefficient, having 240=item $current_eventmask = $w->events
145one or two io watchers and a separate timeout watcher that you reset on
146activity (by calling its C<start> method) is usually more efficient.
147 241
242=item $old_eventmask = $w->events ($new_eventmask)
243
244Returns the previously set event mask and optionally set a new one.
245
246
148=item my $w = EV::timer $after, $repeat, $callback 247=item $w = EV::timer $after, $repeat, $callback
149 248
150=item my $w = EV::timer_ns $after, $repeat, $callback 249=item $w = EV::timer_ns $after, $repeat, $callback
151 250
152Calls 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,
153timer will be restarted after the callback returns. This means that the 252the timer will be restarted (with the $repeat value as $after) after the
154callback would be called roughly every C<$after> seconds, prolonged by the 253callback returns.
155time the callback takes.
156 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
157The 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.
158 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
159=item my $w = EV::timer_abs $at, $interval, $callback 292=item $w = EV::periodic_ns $at, $interval, $callback
160
161=item my $w = EV::timer_abs_ns $at, $interval, $callback
162 293
163Similar 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
164(C<$at>), plus an optional C<$interval>. 295(C<$at>), plus an optional C<$interval>.
165 296
166If 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
167C<$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
168past. It will not automatically repeat. 299past. It will not automatically repeat.
169 300
170If 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
171to time out at the next C<$at + integer * $interval> time. 302to time out at the next C<$at + N * $interval> time.
172 303
173This 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,
174as long as the processing time is less then the interval (otherwise 305as long as the processing time is less then the interval (otherwise
175obviously events will be skipped). 306obviously events will be skipped).
176 307
177Another way to think about it (for the mathematically inclined) is that 308Another way to think about it (for the mathematically inclined) is that
178C<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
179C<$time = $at (mod $interval)>, regardless of any time jumps. 310C<$time = $at (mod $interval)>, regardless of any time jumps.
180 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
181The 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.
182 318
319=item $w->set ($at, $interval)
320
321Reconfigures the watcher, see the constructor above for details. Can be at
322any time.
323
324
183=item my $w = EV::signal $signum, $callback 325=item $w = EV::signal $signal, $callback
184 326
185=item my $w = EV::signal_ns $signum, $callback 327=item $w = EV::signal_ns $signal, $callback
186 328
187Call the callback when signal $signum is received. 329Call the callback when $signal is received (the signal can be specified
330by number or by name, just as with kill or %SIG).
188 331
332EV will grab the signal for the process (the kernel only allows one
333component to receive a signal at a time) when you start a signal watcher,
334and removes it again when you stop it. Perl does the same when you
335add/remove callbacks to %SIG, so watch out.
336
337You can have as many signal watchers per signal as you want.
338
189The 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.
190 466
191=back 467=back
192 468
193=head1 THE EV::Event CLASS 469=head1 THREADS
194 470
195All EV functions creating an event watcher (designated by C<my $w => 471Threads are not supported by this in any way. Perl pseudo-threads is evil
196above) support the following methods on the returned watcher object: 472stuff and must die.
197
198=over 4
199
200=item $w->add ($timeout)
201
202Stops and (re-)starts the event watcher, setting the optional timeout to
203the given value, or clearing the timeout if none is given.
204
205=item $w->start
206
207Stops and (re-)starts the event watcher without touching the timeout.
208
209=item $w->del
210
211=item $w->stop
212
213Stop the event watcher if it was started.
214
215=item $current_callback = $w->cb
216
217=item $old_callback = $w->cb ($new_callback)
218
219Return the previously set callback and optionally set a new one.
220
221=item $current_fh = $w->fh
222
223=item $old_fh = $w->fh ($new_fh)
224
225Returns the previously set filehandle and optionally set a new one (also
226clears the EV::SIGNAL flag when setting a filehandle).
227
228=item $current_signal = $w->signal
229
230=item $old_signal = $w->signal ($new_signal)
231
232Returns the previously set signal number and optionally set a new one (also sets
233the EV::SIGNAL flag when setting a signal).
234
235=item $current_eventmask = $w->events
236
237=item $old_eventmask = $w->events ($new_eventmask)
238
239Returns the previously set event mask and optionally set a new one.
240
241=item $w->timeout ($after, $repeat)
242
243Resets the timeout (see C<EV::timer> for details).
244
245=item $w->timeout_abs ($at, $interval)
246
247Resets the timeout (see C<EV::timer_abs> for details).
248
249=item $w->priority_set ($priority)
250
251Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
252
253=back
254
255=head1 BUGS
256
257Lots. Libevent itself isn't well tested and rather buggy, and this module
258is quite new at the moment.
259
260Please note that the epoll method is not, in general, reliable in programs
261that use fork (even if no libveent calls are being made in the forked
262process). If your program behaves erratically, try setting the environment
263variable C<EVENT_NOEPOLL> first when running the program.
264
265In general, if you fork, then you can only use the EV module in one of the
266children.
267 473
268=cut 474=cut
269 475
270our $DIED = sub { 476our $DIED = sub {
271 warn "EV: error in callback (ignoring): $@"; 477 warn "EV: error in callback (ignoring): $@";
272}; 478};
273 479
274our $NPRI = 4; 480default_loop
275our $BASE = init; 481 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
276priority_init $NPRI;
277 482
278push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"]; 483push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
279 484
2801; 4851;
281 486
282=head1 SEE ALSO 487=head1 SEE ALSO
283 488
284 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
285 L<EV::AnyEvent>. 489 L<EV::DNS>, L<EV::AnyEvent>.
286 490
287=head1 AUTHOR 491=head1 AUTHOR
288 492
289 Marc Lehmann <schmorp@schmorp.de> 493 Marc Lehmann <schmorp@schmorp.de>
290 http://home.schmorp.de/ 494 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines