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

Comparing EV/README (file contents):
Revision 1.7 by root, Sat Nov 3 16:25:49 2007 UTC vs.
Revision 1.8 by root, Thu Nov 8 17:02:10 2007 UTC

… …
15 warn "is called roughly every 2s (repeat = 1)"; 15 warn "is called roughly every 2s (repeat = 1)";
16 }; 16 };
17 17
18 undef $w; # destroy event watcher again 18 undef $w; # destroy event watcher again
19 19
20 my $w = EV::periodic 0, 60, sub { 20 my $w = EV::periodic 0, 60, 0, sub {
21 warn "is called every minute, on the minute, exactly"; 21 warn "is called every minute, on the minute, exactly";
22 }; 22 };
23 23
24 # IO 24 # IO
25 25
… …
146 callback invocation), regardless of wether the watcher was active or 146 callback invocation), regardless of wether the watcher was active or
147 not. 147 not.
148 148
149 $bool = $w->is_active 149 $bool = $w->is_active
150 Returns true if the watcher is active, false otherwise. 150 Returns true if the watcher is active, false otherwise.
151
152 $current_data = $w->data
153 $old_data = $w->data ($new_data)
154 Queries a freely usable data scalar on the watcher and optionally
155 changes it. This is a way to associate custom data with a watcher:
156
157 my $w = EV::timer 60, 0, sub {
158 warn $_[0]->data;
159 };
160 $w->data ("print me!");
151 161
152 $current_cb = $w->cb 162 $current_cb = $w->cb
153 $old_cb = $w->cb ($new_cb) 163 $old_cb = $w->cb ($new_cb)
154 Queries the callback on the watcher and optionally changes it. You 164 Queries the callback on the watcher and optionally changes it. You
155 can do this at any time without the watcher restarting. 165 can do this at any time without the watcher restarting.
… …
231 This behaviour is useful when you have a timeout for some IO 241 This behaviour is useful when you have a timeout for some IO
232 operation. You create a timer object with the same value for $after 242 operation. You create a timer object with the same value for $after
233 and $repeat, and then, in the read/write watcher, run the "again" 243 and $repeat, and then, in the read/write watcher, run the "again"
234 method on the timeout. 244 method on the timeout.
235 245
236 $w = EV::periodic $at, $interval, $callback 246 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
237 $w = EV::periodic_ns $at, $interval, $callback 247 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
238 Similar to EV::timer, but the time is given as an absolute point in 248 Similar to EV::timer, but is not based on relative timeouts but on
239 time ($at), plus an optional $interval. 249 absolute times. Apart from creating "simple" timers that trigger
250 "at" the specified time, it can also be used for non-drifting
251 absolute timers and more complex, cron-like, setups that are not
252 adversely affected by time jumps (i.e. when the system clock is
253 changed by explicit date -s or other means such as ntpd). It is also
254 the most complex watcher type in EV.
240 255
241 If the $interval is zero, then the callback will be called at the 256 It has three distinct "modes":
242 time $at if that is in the future, or as soon as possible if it is
243 in the past. It will not automatically repeat.
244 257
245 If the $interval is nonzero, then the watcher will always be 258 * absolute timer ($interval = $reschedule_cb = 0)
246 scheduled to time out at the next "$at + N * $interval" time. 259 This time simply fires at the wallclock time $at and doesn't
260 repeat. It will not adjust when a time jump occurs, that is, if
261 it is to be run at January 1st 2011 then it will run when the
262 system time reaches or surpasses this time.
247 263
248 This can be used to schedule a callback to run at very regular 264 * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
249 intervals, as long as the processing time is less then the interval 265 In this mode the watcher will always be scheduled to time out at
250 (otherwise obviously events will be skipped). 266 the next "$at + N * $interval" time (for some integer N) and
267 then repeat, regardless of any time jumps.
251 268
269 This can be used to create timers that do not drift with respect
270 to system time:
271
272 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
273
274 That doesn't mean there will always be 3600 seconds in between
275 triggers, but only that the the clalback will be called when the
276 system time shows a full hour (UTC).
277
252 Another way to think about it (for the mathematically inclined) is 278 Another way to think about it (for the mathematically inclined)
253 that EV::periodic will try to run the callback at the next possible 279 is that EV::periodic will try to run the callback in this mode
254 time where "$time = $at (mod $interval)", regardless of any time 280 at the next possible time where "$time = $at (mod $interval)",
255 jumps. 281 regardless of any time jumps.
256 282
257 This periodic timer is based on "wallclock time", that is, if the 283 * manual reschedule mode ($reschedule_cb = coderef)
258 clock changes ("ntp", "date -s" etc.), then the timer will 284 In this mode $interval and $at are both being ignored. Instead,
259 nevertheless run at the specified time. This means it will never 285 each time the periodic watcher gets scheduled, the first
260 drift (it might jitter, but it will not drift). 286 callback ($reschedule_cb) will be called with the watcher as
287 first, and the current time as second argument.
288
289 *This callback MUST NOT stop or destroy this or any other
290 periodic watcher, ever*. If you need to stop it, return 1e30 and
291 stop it afterwards.
292
293 It must return the next time to trigger, based on the passed
294 time value (that is, the lowest time value larger than to the
295 second argument). It will usually be called just before the
296 callback will be triggered, but might be called at other times,
297 too.
298
299 This can be used to create very complex timers, such as a timer
300 that triggers on each midnight, local time (actually 24 hours
301 after the last midnight, to keep the example simple. If you know
302 a way to do it correctly in about the same space (without
303 requiring elaborate modules), drop me a note :):
304
305 my $daily = EV::periodic 0, 0, sub {
306 my ($w, $now) = @_;
307
308 use Time::Local ();
309 my (undef, undef, undef, $d, $m, $y) = localtime $now;
310 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
311 }, sub {
312 print "it's midnight or likely shortly after, now\n";
313 };
261 314
262 The "periodic_ns" variant doesn't start (activate) the newly created 315 The "periodic_ns" variant doesn't start (activate) the newly created
263 watcher. 316 watcher.
264 317
265 $w->set ($at, $interval) 318 $w->set ($at, $interval, $reschedule_cb)
266 Reconfigures the watcher, see the constructor above for details. Can 319 Reconfigures the watcher, see the constructor above for details. Can
267 be at any time. 320 be at any time.
321
322 $w->again
323 Simply stops and starts the watcher again.
268 324
269 $w = EV::signal $signal, $callback 325 $w = EV::signal $signal, $callback
270 $w = EV::signal_ns $signal, $callback 326 $w = EV::signal_ns $signal, $callback
271 Call the callback when $signal is received (the signal can be 327 Call the callback when $signal is received (the signal can be
272 specified by number or by name, just as with kill or %SIG). 328 specified by number or by name, just as with kill or %SIG).

Diff Legend

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