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

Comparing EV/EV.pm (file contents):
Revision 1.27 by root, Sat Nov 3 09:19:58 2007 UTC vs.
Revision 1.32 by root, Thu Nov 8 17:02:10 2007 UTC

… …
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::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
… …
62package EV; 62package EV;
63 63
64use strict; 64use strict;
65 65
66BEGIN { 66BEGIN {
67 our $VERSION = '0.5'; 67 our $VERSION = '0.6';
68 use XSLoader; 68 use XSLoader;
69 XSLoader::load "EV", $VERSION; 69 XSLoader::load "EV", $VERSION;
70} 70}
71 71
72@EV::Io::ISA = 72@EV::Io::ISA =
… …
186 186
187=item $bool = $w->is_active 187=item $bool = $w->is_active
188 188
189Returns true if the watcher is active, false otherwise. 189Returns true if the watcher is active, false otherwise.
190 190
191=item $current_data = $w->data
192
193=item $old_data = $w->data ($new_data)
194
195Queries a freely usable data scalar on the watcher and optionally changes
196it. This is a way to associate custom data with a watcher:
197
198 my $w = EV::timer 60, 0, sub {
199 warn $_[0]->data;
200 };
201 $w->data ("print me!");
202
191=item $current_cb = $w->cb 203=item $current_cb = $w->cb
192 204
193=item $old_cb = $w->cb ($new_cb) 205=item $old_cb = $w->cb ($new_cb)
194 206
195Queries the callback on the watcher and optionally changes it. You can do 207Queries the callback on the watcher and optionally changes it. You can do
… …
285operation. You create a timer object with the same value for C<$after> and 297operation. 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 298C<$repeat>, and then, in the read/write watcher, run the C<again> method
287on the timeout. 299on the timeout.
288 300
289 301
290=item $w = EV::periodic $at, $interval, $callback 302=item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
291 303
292=item $w = EV::periodic_ns $at, $interval, $callback 304=item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
293 305
294Similar to EV::timer, but the time is given as an absolute point in time 306Similar to EV::timer, but is not based on relative timeouts but on
295(C<$at>), plus an optional C<$interval>. 307absolute times. Apart from creating "simple" timers that trigger "at" the
308specified time, it can also be used for non-drifting absolute timers and
309more complex, cron-like, setups that are not adversely affected by time
310jumps (i.e. when the system clock is changed by explicit date -s or other
311means such as ntpd). It is also the most complex watcher type in EV.
296 312
297If the C<$interval> is zero, then the callback will be called at the time 313It has three distinct "modes":
298C<$at> if that is in the future, or as soon as possible if it is in the
299past. It will not automatically repeat.
300 314
301If the C<$interval> is nonzero, then the watcher will always be scheduled 315=over 4
302to time out at the next C<$at + N * $interval> time.
303 316
304This can be used to schedule a callback to run at very regular intervals, 317=item * absolute timer ($interval = $reschedule_cb = 0)
305as long as the processing time is less then the interval (otherwise 318
306obviously events will be skipped). 319This time simply fires at the wallclock time C<$at> and doesn't repeat. It
320will not adjust when a time jump occurs, that is, if it is to be run
321at January 1st 2011 then it will run when the system time reaches or
322surpasses this time.
323
324=item * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
325
326In this mode the watcher will always be scheduled to time out at the
327next C<$at + N * $interval> time (for some integer N) and then repeat,
328regardless of any time jumps.
329
330This can be used to create timers that do not drift with respect to system
331time:
332
333 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
334
335That doesn't mean there will always be 3600 seconds in between triggers,
336but only that the the clalback will be called when the system time shows a
337full hour (UTC).
307 338
308Another way to think about it (for the mathematically inclined) is that 339Another way to think about it (for the mathematically inclined) is that
309EV::periodic will try to run the callback at the next possible time where 340EV::periodic will try to run the callback in this mode at the next
310C<$time = $at (mod $interval)>, regardless of any time jumps. 341possible time where C<$time = $at (mod $interval)>, regardless of any time
342jumps.
311 343
312This periodic timer is based on "wallclock time", that is, if the clock 344=item * manual reschedule mode ($reschedule_cb = coderef)
313changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at 345
314the specified time. This means it will never drift (it might jitter, but 346In this mode $interval and $at are both being ignored. Instead, each time
315it will not drift). 347the periodic watcher gets scheduled, the first callback ($reschedule_cb)
348will be called with the watcher as first, and the current time as second
349argument.
350
351I<This callback MUST NOT stop or destroy this or any other periodic
352watcher, ever>. If you need to stop it, return 1e30 and stop it
353afterwards.
354
355It must return the next time to trigger, based on the passed time value
356(that is, the lowest time value larger than to the second argument). It
357will usually be called just before the callback will be triggered, but
358might be called at other times, too.
359
360This can be used to create very complex timers, such as a timer that
361triggers on each midnight, local time (actually 24 hours after the last
362midnight, to keep the example simple. If you know a way to do it correctly
363in about the same space (without requiring elaborate modules), drop me a
364note :):
365
366 my $daily = EV::periodic 0, 0, sub {
367 my ($w, $now) = @_;
368
369 use Time::Local ();
370 my (undef, undef, undef, $d, $m, $y) = localtime $now;
371 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
372 }, sub {
373 print "it's midnight or likely shortly after, now\n";
374 };
375
376=back
316 377
317The C<periodic_ns> variant doesn't start (activate) the newly created watcher. 378The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
318 379
319=item $w->set ($at, $interval) 380=item $w->set ($at, $interval, $reschedule_cb)
320 381
321Reconfigures the watcher, see the constructor above for details. Can be at 382Reconfigures the watcher, see the constructor above for details. Can be at
322any time. 383any time.
384
385=item $w->again
386
387Simply stops and starts the watcher again.
323 388
324 389
325=item $w = EV::signal $signal, $callback 390=item $w = EV::signal $signal, $callback
326 391
327=item $w = EV::signal_ns $signal, $callback 392=item $w = EV::signal_ns $signal, $callback
… …
475 540
476our $DIED = sub { 541our $DIED = sub {
477 warn "EV: error in callback (ignoring): $@"; 542 warn "EV: error in callback (ignoring): $@";
478}; 543};
479 544
480init 545default_loop
481 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?'; 546 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
482 547
483push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"]; 548push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
484 549
4851; 5501;

Diff Legend

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