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

Comparing EV/EV.pm (file contents):
Revision 1.25 by root, Fri Nov 2 22:18:49 2007 UTC vs.
Revision 1.30 by root, Thu Nov 8 02:19:36 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
40 }; 40 };
41 41
42 # CHILD/PID STATUS CHANGES 42 # CHILD/PID STATUS CHANGES
43 43
44 my $w = EV::child 666, sub { 44 my $w = EV::child 666, sub {
45 my ($w, $revents, $status) = @_; 45 my ($w, $revents) = @_;
46 # my $pid = $w->rpid;
47 my $status = $w->rstatus;
46 }; 48 };
47 49
48 # MAINLOOP 50 # MAINLOOP
49 EV::loop; # loop until EV::loop_done is called 51 EV::loop; # loop until EV::loop_done is called
50 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 52 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
60package EV; 62package EV;
61 63
62use strict; 64use strict;
63 65
64BEGIN { 66BEGIN {
65 our $VERSION = '0.5'; 67 our $VERSION = '0.51';
66 use XSLoader; 68 use XSLoader;
67 XSLoader::load "EV", $VERSION; 69 XSLoader::load "EV", $VERSION;
68} 70}
69 71
70@EV::Io::ISA = 72@EV::Io::ISA =
184 186
185=item $bool = $w->is_active 187=item $bool = $w->is_active
186 188
187Returns true if the watcher is active, false otherwise. 189Returns true if the watcher is active, false otherwise.
188 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
189=item $current_cb = $w->cb 203=item $current_cb = $w->cb
190 204
191=item $old_cb = $w->cb ($new_cb) 205=item $old_cb = $w->cb ($new_cb)
192 206
193Queries 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
283operation. 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
284C<$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
285on the timeout. 299on the timeout.
286 300
287 301
288=item $w = EV::periodic $at, $interval, $callback 302=item $w = EV::periodic $at, $interval, $reschedule_cb, $callback
289 303
290=item $w = EV::periodic_ns $at, $interval, $callback 304=item $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
291 305
292Similar 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
293(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.
294 312
295If the C<$interval> is zero, then the callback will be called at the time 313It has three distinct "modes":
296C<$at> if that is in the future, or as soon as possible if it is in the
297past. It will not automatically repeat.
298 314
299If the C<$interval> is nonzero, then the watcher will always be scheduled 315=over 4
300to time out at the next C<$at + N * $interval> time.
301 316
302This can be used to schedule a callback to run at very regular intervals, 317=item * absolute timer ($interval = $reschedule_cb = 0)
303as long as the processing time is less then the interval (otherwise 318
304obviously 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).
305 338
306Another way to think about it (for the mathematically inclined) is that 339Another way to think about it (for the mathematically inclined) is that
307EV::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
308C<$time = $at (mod $interval)>, regardless of any time jumps. 341possible time where C<$time = $at (mod $interval)>, regardless of any time
342jumps.
309 343
310This periodic timer is based on "wallclock time", that is, if the clock 344=item * manual reschedule mode ($reschedule_cb = coderef)
311changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at 345
312the 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
313it 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 the event watcher, ever.>
352
353It must return the next time to trigger, based on the passed time value
354(that is, the lowest time value larger than to the second argument). It
355will usually be called just before the callback will be triggered, but
356might be called at other times, too.
357
358This can be used to create very complex timers, such as a timer that
359triggers on each midnight, local time (actually 24 hours after the last
360midnight, to keep the example simple. If you know a way to do it correctly
361in about the same space (without requiring elaborate modules), drop me a
362note :):
363
364 my $daily = EV::periodic 0, 0, sub {
365 my ($w, $now) = @_;
366
367 use Time::Local ();
368 my (undef, undef, undef, $d, $m, $y) = localtime $now;
369 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
370 }, sub {
371 print "it's midnight or likely shortly after, now\n";
372 };
373
374=back
314 375
315The C<periodic_ns> variant doesn't start (activate) the newly created watcher. 376The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
316 377
317=item $w->set ($at, $interval) 378=item $w->set ($at, $interval, $reschedule_cb)
318 379
319Reconfigures the watcher, see the constructor above for details. Can be at 380Reconfigures the watcher, see the constructor above for details. Can be at
320any time. 381any time.
382
383=item $w->again
384
385Simply stops and starts the watcher again.
321 386
322 387
323=item $w = EV::signal $signal, $callback 388=item $w = EV::signal $signal, $callback
324 389
325=item $w = EV::signal_ns $signal, $callback 390=item $w = EV::signal_ns $signal, $callback
356Call the callback when a status change for pid C<$pid> (or any pid 421Call the callback when a status change for pid C<$pid> (or any pid
357if C<$pid> is 0) has been received. More precisely: when the process 422if C<$pid> is 0) has been received. More precisely: when the process
358receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all 423receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
359changed/zombie children and call the callback. 424changed/zombie children and call the callback.
360 425
361Unlike all other callbacks, this callback will be called with an 426You can access both status and pid by using the C<rstatus> and C<rpid>
362additional third argument which is the exit status. See the C<waitpid> 427methods on the watcher object.
363function for details.
364 428
365You can have as many pid watchers per pid as you want. 429You can have as many pid watchers per pid as you want.
366 430
367The C<child_ns> variant doesn't start (activate) the newly created watcher. 431The C<child_ns> variant doesn't start (activate) the newly created watcher.
368 432
374=item $current_pid = $w->pid 438=item $current_pid = $w->pid
375 439
376=item $old_pid = $w->pid ($new_pid) 440=item $old_pid = $w->pid ($new_pid)
377 441
378Returns the previously set process id and optionally set a new one. 442Returns the previously set process id and optionally set a new one.
443
444=item $exit_status = $w->rstatus
445
446Return the exit/wait status (as returned by waitpid, see the waitpid entry
447in perlfunc).
448
449=item $pid = $w->rpid
450
451Return the pid of the awaited child (useful when you have installed a
452watcher for all pids).
379 453
380 454
381=item $w = EV::idle $callback 455=item $w = EV::idle $callback
382 456
383=item $w = EV::idle_ns $callback 457=item $w = EV::idle_ns $callback
464 538
465our $DIED = sub { 539our $DIED = sub {
466 warn "EV: error in callback (ignoring): $@"; 540 warn "EV: error in callback (ignoring): $@";
467}; 541};
468 542
469init; 543default_loop
544 or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';
470 545
471push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"]; 546push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
472 547
4731; 5481;
474 549

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines