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

Comparing EV/EV.pm (file contents):
Revision 1.20 by root, Thu Nov 1 17:17:32 2007 UTC vs.
Revision 1.51 by root, Sat Nov 24 16:12:37 2007 UTC

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 my $w = EV::periodic 0, 60, sub { 21 my $w = EV::periodic 0, 60, 0, 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, 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 receive the watcher and event mask
29 warn "stdin is readable, you entered: ", <STDIN>; 29 warn "stdin is readable, you entered: ", <STDIN>;
30 }; 30 };
31 31
32 # SIGNALS 32 # SIGNALS
33 33
34 my $w = EV::signal 'QUIT', sub { 34 my $w = EV::signal 'QUIT', sub {
35 warn "sigquit received\n"; 35 warn "sigquit received\n";
36 }; 36 };
37 37
38 # CHILD/PID STATUS CHANGES
39
38 my $w = EV::signal 3, sub { 40 my $w = EV::child 666, sub {
39 warn "sigquit received (this is GNU/Linux, right?)\n"; 41 my ($w, $revents) = @_;
42 my $status = $w->rstatus;
40 }; 43 };
41
42 # CHILD/PID STATUS CHANGES
43
44 my $w = EV::child 666, sub {
45 my ($w, $revents, $status) = @_;
46 };
47 44
48 # MAINLOOP 45 # MAINLOOP
49 EV::loop; # loop until EV::loop_done is called 46 EV::loop; # loop until EV::unloop is called or all watchers stop
50 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 47 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
51 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 48 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
52 49
53=head1 DESCRIPTION 50=head1 DESCRIPTION
54 51
60package EV; 57package EV;
61 58
62use strict; 59use strict;
63 60
64BEGIN { 61BEGIN {
65 our $VERSION = '0.1'; 62 our $VERSION = '1.3';
66 use XSLoader; 63 use XSLoader;
67 XSLoader::load "EV", $VERSION; 64 XSLoader::load "EV", $VERSION;
68} 65}
69 66
70@EV::Io::ISA = 67@EV::IO::ISA =
71@EV::Timer::ISA = 68@EV::Timer::ISA =
72@EV::Periodic::ISA = 69@EV::Periodic::ISA =
73@EV::Signal::ISA = 70@EV::Signal::ISA =
74@EV::Idle::ISA = 71@EV::Idle::ISA =
75@EV::Prepare::ISA = 72@EV::Prepare::ISA =
96 93
97Returns the time the last event loop iteration has been started. This 94Returns the time the last event loop iteration has been started. This
98is the time that (relative) timers are based on, and refering to it is 95is the time that (relative) timers are based on, and refering to it is
99usually faster then calling EV::time. 96usually faster then calling EV::time.
100 97
101=item $method = EV::ev_method 98=item $method = EV::method
102 99
103Returns an integer describing the backend used by libev (EV::METHOD_SELECT 100Returns an integer describing the backend used by libev (EV::METHOD_SELECT
104or EV::METHOD_EPOLL). 101or EV::METHOD_EPOLL).
105 102
106=item EV::loop [$flags] 103=item EV::loop [$flags]
107 104
108Begin checking for events and calling callbacks. It returns when a 105Begin checking for events and calling callbacks. It returns when a
109callback calls EV::loop_done. 106callback calls EV::unloop.
110 107
111The $flags argument can be one of the following: 108The $flags argument can be one of the following:
112 109
113 0 as above 110 0 as above
114 EV::LOOP_ONESHOT block at most once (wait, but do not loop) 111 EV::LOOP_ONESHOT block at most once (wait, but do not loop)
115 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait) 112 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
116 113
117=item EV::loop_done [$how] 114=item EV::unloop [$how]
118 115
119When called with no arguments or an argument of 1, makes the innermost 116When called with no arguments or an argument of EV::UNLOOP_ONE, makes the
120call to EV::loop return. 117innermost call to EV::loop return.
121 118
122When called with an agrument of 2, all calls to EV::loop will return as 119When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
123fast as possible. 120fast as possible.
121
122=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
123
124This function rolls together an I/O and a timer watcher for a single
125one-shot event without the need for managing a watcher object.
126
127If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
128must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
129| EV::WRITE>, indicating the type of I/O event you want to wait for. If
130you do not want to wait for some I/O event, specify C<undef> for
131C<$fh_or_undef> and C<0> for C<$events>).
132
133If timeout is C<undef> or negative, then there will be no
134timeout. Otherwise a EV::timer with this value will be started.
135
136When an error occurs or either the timeout or I/O watcher triggers, then
137the callback will be called with the received event set (in general
138you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
139C<EV::WRITE> and C<EV::TIMEOUT>).
140
141EV::once doesn't return anything: the watchers stay active till either
142of them triggers, then they will be stopped and freed, and the callback
143invoked.
124 144
125=back 145=back
126 146
127=head2 WATCHER 147=head2 WATCHER
128 148
150In the rare case where one wants to create a watcher but not start it at 170In the rare case where one wants to create a watcher but not start it at
151the same time, each constructor has a variant with a trailing C<_ns> in 171the same time, each constructor has a variant with a trailing C<_ns> in
152its name, e.g. EV::io has a non-starting variant EV::io_ns and so on. 172its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
153 173
154Please note that a watcher will automatically be stopped when the watcher 174Please note that a watcher will automatically be stopped when the watcher
155object is returned, so you I<need> to keep the watcher objects returned by 175object is destroyed, so you I<need> to keep the watcher objects returned by
156the constructors. 176the constructors.
177
178Also, all methods changing some aspect of a watcher (->set, ->priority,
179->fh and so on) automatically stop and start it again if it is active,
180which means pending events get lost.
157 181
158=head2 WATCHER TYPES 182=head2 WATCHER TYPES
159 183
160Now lets move to the existing watcher types and asociated methods. 184Now lets move to the existing watcher types and asociated methods.
161 185
180 204
181=item $bool = $w->is_active 205=item $bool = $w->is_active
182 206
183Returns true if the watcher is active, false otherwise. 207Returns true if the watcher is active, false otherwise.
184 208
209=item $current_data = $w->data
210
211=item $old_data = $w->data ($new_data)
212
213Queries a freely usable data scalar on the watcher and optionally changes
214it. This is a way to associate custom data with a watcher:
215
216 my $w = EV::timer 60, 0, sub {
217 warn $_[0]->data;
218 };
219 $w->data ("print me!");
220
185=item $current_cb = $w->cb 221=item $current_cb = $w->cb
186 222
187=item $old_cb = $w->cb ($new_cb) 223=item $old_cb = $w->cb ($new_cb)
188 224
189Queries the callback on the watcher and optionally changes it. You cna do 225Queries the callback on the watcher and optionally changes it. You can do
190this at any time. 226this at any time without the watcher restarting.
227
228=item $current_priority = $w->priority
229
230=item $old_priority = $w->priority ($new_priority)
231
232Queries the priority on the watcher and optionally changes it. Pending
233watchers with higher priority will be invoked first. The valid range of
234priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
235-2). If the priority is outside this range it will automatically be
236normalised to the nearest valid priority.
237
238The default priority of any newly-created watcher is 0.
239
240Note that the priority semantics have not yet been fleshed out and are
241subject to almost certain change.
191 242
192=item $w->trigger ($revents) 243=item $w->trigger ($revents)
193 244
194Call the callback *now* with the given event mask. 245Call the callback *now* with the given event mask.
195 246
247=item $previous_state = $w->keepalive ($bool)
248
249Normally, C<EV::loop> will return when there are no active watchers
250(which is a "deadlock" because no progress can be made anymore). This is
251convinient because it allows you to start your watchers (and your jobs),
252call C<EV::loop> once and when it returns you know that all your jobs are
253finished (or they forgot to register some watchers for their task :).
254
255Sometimes, however, this gets in your way, for example when you the module
256that calls C<EV::loop> (usually the main program) is not the same module
257as a long-living watcher (for example a DNS client module written by
258somebody else even). Then you might want any outstanding requests to be
259handled, but you would not want to keep C<EV::loop> from returning just
260because you happen to have this long-running UDP port watcher.
261
262In this case you can clear the keepalive status, which means that even
263though your watcher is active, it won't keep C<EV::loop> from returning.
264
265The initial value for keepalive is true (enabled), and you cna change it
266any time.
267
268Example: Register an IO watcher for some UDP socket but do not keep the
269event loop from running just because of that watcher.
270
271 my $udp_socket = ...
272 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
273 $udp_watcher->keepalive (0);
196 274
197=item $w = EV::io $fileno_or_fh, $eventmask, $callback 275=item $w = EV::io $fileno_or_fh, $eventmask, $callback
198 276
199=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 277=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
200 278
233Calls the callback after C<$after> seconds. If C<$repeat> is non-zero, 311Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
234the timer will be restarted (with the $repeat value as $after) after the 312the timer will be restarted (with the $repeat value as $after) after the
235callback returns. 313callback returns.
236 314
237This means that the callback would be called roughly after C<$after> 315This means that the callback would be called roughly after C<$after>
238seconds, and then every C<$repeat> seconds. "Roughly" because the time of 316seconds, and then every C<$repeat> seconds. The timer does his best not
239callback processing is not taken into account, so the timer will slowly 317to drift, but it will not invoke the timer more often then once per event
240drift. If that isn't acceptable, look at EV::periodic. 318loop iteration, and might drift in other cases. If that isn't acceptable,
319look at EV::periodic, which can provide long-term stable timers.
241 320
242The timer is based on a monotonic clock, that is if somebody is sitting 321The timer is based on a monotonic clock, that is, if somebody is sitting
243in front of the machine while the timer is running and changes the system 322in front of the machine while the timer is running and changes the system
244clock, the timer will nevertheless run (roughly) the same time. 323clock, the timer will nevertheless run (roughly) the same time.
245 324
246The C<timer_ns> variant doesn't start (activate) the newly created watcher. 325The C<timer_ns> variant doesn't start (activate) the newly created watcher.
247 326
252 331
253=item $w->again 332=item $w->again
254 333
255Similar to the C<start> method, but has special semantics for repeating timers: 334Similar to the C<start> method, but has special semantics for repeating timers:
256 335
336If the timer is active and non-repeating, it will be stopped.
337
257If the timer is active and repeating, reset the timeout to occur 338If the timer is active and repeating, reset the timeout to occur
258C<$repeat> seconds after now. 339C<$repeat> seconds after now.
259 340
260If the timer is active and non-repeating, it will be stopped.
261
262If the timer is in active and repeating, start it. 341If the timer is inactive and repeating, start it using the repeat value.
263 342
264Otherwise do nothing. 343Otherwise do nothing.
265 344
266This behaviour is useful when you have a timeout for some IO 345This behaviour is useful when you have a timeout for some IO
267operation. You create a timer object with the same value for C<$after> and 346operation. You create a timer object with the same value for C<$after> and
268C<$repeat>, and then, in the read/write watcher, run the C<again> method 347C<$repeat>, and then, in the read/write watcher, run the C<again> method
269on the timeout. 348on the timeout.
270 349
271 350
272=item $w = EV::periodic $at, $interval, $callback 351=item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
273 352
274=item $w = EV::periodic_ns $at, $interval, $callback 353=item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
275 354
276Similar to EV::timer, but the time is given as an absolute point in time 355Similar to EV::timer, but is not based on relative timeouts but on
277(C<$at>), plus an optional C<$interval>. 356absolute times. Apart from creating "simple" timers that trigger "at" the
357specified time, it can also be used for non-drifting absolute timers and
358more complex, cron-like, setups that are not adversely affected by time
359jumps (i.e. when the system clock is changed by explicit date -s or other
360means such as ntpd). It is also the most complex watcher type in EV.
278 361
279If the C<$interval> is zero, then the callback will be called at the time 362It has three distinct "modes":
280C<$at> if that is in the future, or as soon as possible if it is in the
281past. It will not automatically repeat.
282 363
283If the C<$interval> is nonzero, then the watcher will always be scheduled 364=over 4
284to time out at the next C<$at + N * $interval> time.
285 365
286This can be used to schedule a callback to run at very regular intervals, 366=item * absolute timer ($interval = $reschedule_cb = 0)
287as long as the processing time is less then the interval (otherwise 367
288obviously events will be skipped). 368This time simply fires at the wallclock time C<$at> and doesn't repeat. It
369will not adjust when a time jump occurs, that is, if it is to be run
370at January 1st 2011 then it will run when the system time reaches or
371surpasses this time.
372
373=item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
374
375In this mode the watcher will always be scheduled to time out at the
376next C<$at + N * $interval> time (for some integer N) and then repeat,
377regardless of any time jumps.
378
379This can be used to create timers that do not drift with respect to system
380time:
381
382 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
383
384That doesn't mean there will always be 3600 seconds in between triggers,
385but only that the the clalback will be called when the system time shows a
386full hour (UTC).
289 387
290Another way to think about it (for the mathematically inclined) is that 388Another way to think about it (for the mathematically inclined) is that
291EV::periodic will try to run the callback at the next possible time where 389EV::periodic will try to run the callback in this mode at the next
292C<$time = $at (mod $interval)>, regardless of any time jumps. 390possible time where C<$time = $at (mod $interval)>, regardless of any time
391jumps.
293 392
294This periodic timer is based on "wallclock time", that is, if the clock 393=item * manual reschedule mode ($reschedule_cb = coderef)
295changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at 394
296the specified time. 395In this mode $interval and $at are both being ignored. Instead, each
396time the periodic watcher gets scheduled, the reschedule callback
397($reschedule_cb) will be called with the watcher as first, and the current
398time as second argument.
399
400I<This callback MUST NOT stop or destroy this or any other periodic
401watcher, ever>. If you need to stop it, return 1e30 and stop it
402afterwards.
403
404It must return the next time to trigger, based on the passed time value
405(that is, the lowest time value larger than to the second argument). It
406will usually be called just before the callback will be triggered, but
407might be called at other times, too.
408
409This can be used to create very complex timers, such as a timer that
410triggers on each midnight, local time (actually 24 hours after the last
411midnight, to keep the example simple. If you know a way to do it correctly
412in about the same space (without requiring elaborate modules), drop me a
413note :):
414
415 my $daily = EV::periodic 0, 0, sub {
416 my ($w, $now) = @_;
417
418 use Time::Local ();
419 my (undef, undef, undef, $d, $m, $y) = localtime $now;
420 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
421 }, sub {
422 print "it's midnight or likely shortly after, now\n";
423 };
424
425=back
297 426
298The C<periodic_ns> variant doesn't start (activate) the newly created watcher. 427The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
299 428
300=item $w->set ($at, $interval) 429=item $w->set ($at, $interval, $reschedule_cb)
301 430
302Reconfigures the watcher, see the constructor above for details. Can be at 431Reconfigures the watcher, see the constructor above for details. Can be at
303any time. 432any time.
433
434=item $w->again
435
436Simply stops and starts the watcher again.
304 437
305 438
306=item $w = EV::signal $signal, $callback 439=item $w = EV::signal $signal, $callback
307 440
308=item $w = EV::signal_ns $signal, $callback 441=item $w = EV::signal_ns $signal, $callback
322=item $w->set ($signal) 455=item $w->set ($signal)
323 456
324Reconfigures the watcher, see the constructor above for details. Can be at 457Reconfigures the watcher, see the constructor above for details. Can be at
325any time. 458any time.
326 459
460=item $current_signum = $w->signal
461
462=item $old_signum = $w->signal ($new_signal)
463
464Returns the previously set signal (always as a number not name) and
465optionally set a new one.
466
327 467
328=item $w = EV::child $pid, $callback 468=item $w = EV::child $pid, $callback
329 469
330=item $w = EV::child_ns $pid, $callback 470=item $w = EV::child_ns $pid, $callback
331 471
332Call the callback when a status change for pid C<$pid> (or any pid 472Call the callback when a status change for pid C<$pid> (or any pid
333if C<$pid> is 0) has been received. More precisely: when the process 473if C<$pid> is 0) has been received. More precisely: when the process
334receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all 474receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
335changed/zombie children and call the callback. 475changed/zombie children and call the callback.
336 476
337Unlike all other callbacks, this callback will be called with an 477You can access both status and pid by using the C<rstatus> and C<rpid>
338additional third argument which is the exit status. See the C<waitpid> 478methods on the watcher object.
339function for details.
340 479
341You can have as many pid watchers per pid as you want. 480You can have as many pid watchers per pid as you want.
342 481
343The C<child_ns> variant doesn't start (activate) the newly created watcher. 482The C<child_ns> variant doesn't start (activate) the newly created watcher.
344 483
345=item $w->set ($pid) 484=item $w->set ($pid)
346 485
347Reconfigures the watcher, see the constructor above for details. Can be at 486Reconfigures the watcher, see the constructor above for details. Can be at
348any time. 487any time.
488
489=item $current_pid = $w->pid
490
491=item $old_pid = $w->pid ($new_pid)
492
493Returns the previously set process id and optionally set a new one.
494
495=item $exit_status = $w->rstatus
496
497Return the exit/wait status (as returned by waitpid, see the waitpid entry
498in perlfunc).
499
500=item $pid = $w->rpid
501
502Return the pid of the awaited child (useful when you have installed a
503watcher for all pids).
349 504
350 505
351=item $w = EV::idle $callback 506=item $w = EV::idle $callback
352 507
353=item $w = EV::idle_ns $callback 508=item $w = EV::idle_ns $callback
391 # do nothing unless active 546 # do nothing unless active
392 $dispatcher->{_event_queue_h} 547 $dispatcher->{_event_queue_h}
393 or return; 548 or return;
394 549
395 # make the dispatcher handle any outstanding stuff 550 # make the dispatcher handle any outstanding stuff
551 ... not shown
396 552
397 # create an IO watcher for each and every socket 553 # create an IO watcher for each and every socket
398 @snmp_watcher = ( 554 @snmp_watcher = (
399 (map { EV::io $_, EV::READ, sub { } } 555 (map { EV::io $_, EV::READ, sub { } }
400 keys %{ $dispatcher->{_descriptors} }), 556 keys %{ $dispatcher->{_descriptors} }),
557
558 EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
559 ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
560 0, sub { },
401 ); 561 );
402
403 # if there are any timeouts, also create a timer
404 push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
405 if $event->[Net::SNMP::Dispatcher::_ACTIVE];
406 }; 562 };
407 563
408The callbacks are irrelevant, the only purpose of those watchers is 564The callbacks are irrelevant (and are not even being called), the
409to wake up the process as soon as one of those events occurs (socket 565only purpose of those watchers is to wake up the process as soon as
410readable, or timer timed out). The corresponding EV::check watcher will then 566one of those events occurs (socket readable, or timer timed out). The
411clean up: 567corresponding EV::check watcher will then clean up:
412 568
413 our $snmp_check = EV::check sub { 569 our $snmp_check = EV::check sub {
414 # destroy all watchers 570 # destroy all watchers
415 @snmp_watcher = (); 571 @snmp_watcher = ();
416 572
417 # make the dispatcher handle any new stuff 573 # make the dispatcher handle any new stuff
574 ... not shown
418 }; 575 };
419 576
420The callbacks of the created watchers will not be called as the watchers 577The callbacks of the created watchers will not be called as the watchers
421are destroyed before this cna happen (remember EV::check gets called 578are destroyed before this cna happen (remember EV::check gets called
422first). 579first).
425 582
426=back 583=back
427 584
428=head1 THREADS 585=head1 THREADS
429 586
430Threads are not supported by this in any way. Perl pseudo-threads is evil 587Threads are not supported by this module in any way. Perl pseudo-threads
431stuff and must die. 588is evil stuff and must die. As soon as Perl gains real threads I will work
589on thread support for it.
590
591=head1 FORK
592
593Most of the "improved" event delivering mechanisms of modern operating
594systems have quite a few problems with fork(2) (to put it bluntly: it is
595not supported and usually destructive). Libev makes it possible to work
596around this by having a function that recreates the kernel state after
597fork in the child.
598
599On non-win32 platforms, this module requires the pthread_atfork
600functionality to do this automatically for you. This function is quite
601buggy on most BSDs, though, so YMMV. The overhead for this is quite
602negligible, because everything the function currently does is set a flag
603that is checked only when the event loop gets used the next time, so when
604you do fork but not use EV, the overhead is minimal.
605
606On win32, there is no notion of fork so all this doesn't apply, of course.
432 607
433=cut 608=cut
434 609
435our $DIED = sub { 610our $DIED = sub {
436 warn "EV: error in callback (ignoring): $@"; 611 warn "EV: error in callback (ignoring): $@";
437}; 612};
438 613
439init; 614default_loop
440 615 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
441push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
442 616
4431; 6171;
444 618
445=head1 SEE ALSO 619=head1 SEE ALSO
446 620
447 L<EV::DNS>, L<EV::AnyEvent>. 621 L<EV::DNS>.
448 622
449=head1 AUTHOR 623=head1 AUTHOR
450 624
451 Marc Lehmann <schmorp@schmorp.de> 625 Marc Lehmann <schmorp@schmorp.de>
452 http://home.schmorp.de/ 626 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines