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.9 by root, Mon Nov 12 01:23:21 2007 UTC

… …
9 9
10 my $w = EV::timer 2, 0, sub { 10 my $w = EV::timer 2, 0, sub {
11 warn "is called after 2s"; 11 warn "is called after 2s";
12 }; 12 };
13 13
14 my $w = EV::timer 2, 1, sub { 14 my $w = EV::timer 2, 2, sub {
15 warn "is called roughly every 2s (repeat = 1)"; 15 warn "is called roughly every 2s (repeat = 2)";
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
26 my $w = EV::io *STDIN, EV::READ, sub { 26 my $w = EV::io *STDIN, EV::READ, sub {
27 my ($w, $revents) = @_; # all callbacks get the watcher object and event mask 27 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
28 warn "stdin is readable, you entered: ", <STDIN>; 28 warn "stdin is readable, you entered: ", <STDIN>;
29 }; 29 };
30 30
31 # SIGNALS 31 # SIGNALS
32 32
33 my $w = EV::signal 'QUIT', sub { 33 my $w = EV::signal 'QUIT', sub {
34 warn "sigquit received\n"; 34 warn "sigquit received\n";
35 }; 35 };
36 36
37 my $w = EV::signal 3, sub {
38 warn "sigquit received (this is GNU/Linux, right?)\n";
39 };
40
41 # CHILD/PID STATUS CHANGES 37 # CHILD/PID STATUS CHANGES
42 38
43 my $w = EV::child 666, sub { 39 my $w = EV::child 666, sub {
44 my ($w, $revents) = @_; 40 my ($w, $revents) = @_;
45 # my $pid = $w->rpid;
46 my $status = $w->rstatus; 41 my $status = $w->rstatus;
47 }; 42 };
48 43
49 # MAINLOOP 44 # MAINLOOP
50 EV::loop; # loop until EV::loop_done is called 45 EV::loop; # loop until EV::loop_done is called or all watchers stop
51 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 46 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
52 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 47 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
53 48
54DESCRIPTION 49DESCRIPTION
55 This module provides an interface to libev 50 This module provides an interface to libev
… …
146 callback invocation), regardless of wether the watcher was active or 141 callback invocation), regardless of wether the watcher was active or
147 not. 142 not.
148 143
149 $bool = $w->is_active 144 $bool = $w->is_active
150 Returns true if the watcher is active, false otherwise. 145 Returns true if the watcher is active, false otherwise.
146
147 $current_data = $w->data
148 $old_data = $w->data ($new_data)
149 Queries a freely usable data scalar on the watcher and optionally
150 changes it. This is a way to associate custom data with a watcher:
151
152 my $w = EV::timer 60, 0, sub {
153 warn $_[0]->data;
154 };
155 $w->data ("print me!");
151 156
152 $current_cb = $w->cb 157 $current_cb = $w->cb
153 $old_cb = $w->cb ($new_cb) 158 $old_cb = $w->cb ($new_cb)
154 Queries the callback on the watcher and optionally changes it. You 159 Queries the callback on the watcher and optionally changes it. You
155 can do this at any time without the watcher restarting. 160 can do this at any time without the watcher restarting.
… …
231 This behaviour is useful when you have a timeout for some IO 236 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 237 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" 238 and $repeat, and then, in the read/write watcher, run the "again"
234 method on the timeout. 239 method on the timeout.
235 240
236 $w = EV::periodic $at, $interval, $callback 241 $w = EV::periodic $at, $interval, $reschedule_cb, $callback
237 $w = EV::periodic_ns $at, $interval, $callback 242 $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
238 Similar to EV::timer, but the time is given as an absolute point in 243 Similar to EV::timer, but is not based on relative timeouts but on
239 time ($at), plus an optional $interval. 244 absolute times. Apart from creating "simple" timers that trigger
245 "at" the specified time, it can also be used for non-drifting
246 absolute timers and more complex, cron-like, setups that are not
247 adversely affected by time jumps (i.e. when the system clock is
248 changed by explicit date -s or other means such as ntpd). It is also
249 the most complex watcher type in EV.
240 250
241 If the $interval is zero, then the callback will be called at the 251 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 252
245 If the $interval is nonzero, then the watcher will always be 253 * absolute timer ($interval = $reschedule_cb = 0)
246 scheduled to time out at the next "$at + N * $interval" time. 254 This time simply fires at the wallclock time $at and doesn't
255 repeat. It will not adjust when a time jump occurs, that is, if
256 it is to be run at January 1st 2011 then it will run when the
257 system time reaches or surpasses this time.
247 258
248 This can be used to schedule a callback to run at very regular 259 * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
249 intervals, as long as the processing time is less then the interval 260 In this mode the watcher will always be scheduled to time out at
250 (otherwise obviously events will be skipped). 261 the next "$at + N * $interval" time (for some integer N) and
262 then repeat, regardless of any time jumps.
251 263
264 This can be used to create timers that do not drift with respect
265 to system time:
266
267 my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
268
269 That doesn't mean there will always be 3600 seconds in between
270 triggers, but only that the the clalback will be called when the
271 system time shows a full hour (UTC).
272
252 Another way to think about it (for the mathematically inclined) is 273 Another way to think about it (for the mathematically inclined)
253 that EV::periodic will try to run the callback at the next possible 274 is that EV::periodic will try to run the callback in this mode
254 time where "$time = $at (mod $interval)", regardless of any time 275 at the next possible time where "$time = $at (mod $interval)",
255 jumps. 276 regardless of any time jumps.
256 277
257 This periodic timer is based on "wallclock time", that is, if the 278 * manual reschedule mode ($reschedule_cb = coderef)
258 clock changes ("ntp", "date -s" etc.), then the timer will 279 In this mode $interval and $at are both being ignored. Instead,
259 nevertheless run at the specified time. This means it will never 280 each time the periodic watcher gets scheduled, the first
260 drift (it might jitter, but it will not drift). 281 callback ($reschedule_cb) will be called with the watcher as
282 first, and the current time as second argument.
283
284 *This callback MUST NOT stop or destroy this or any other
285 periodic watcher, ever*. If you need to stop it, return 1e30 and
286 stop it afterwards.
287
288 It must return the next time to trigger, based on the passed
289 time value (that is, the lowest time value larger than to the
290 second argument). It will usually be called just before the
291 callback will be triggered, but might be called at other times,
292 too.
293
294 This can be used to create very complex timers, such as a timer
295 that triggers on each midnight, local time (actually 24 hours
296 after the last midnight, to keep the example simple. If you know
297 a way to do it correctly in about the same space (without
298 requiring elaborate modules), drop me a note :):
299
300 my $daily = EV::periodic 0, 0, sub {
301 my ($w, $now) = @_;
302
303 use Time::Local ();
304 my (undef, undef, undef, $d, $m, $y) = localtime $now;
305 86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
306 }, sub {
307 print "it's midnight or likely shortly after, now\n";
308 };
261 309
262 The "periodic_ns" variant doesn't start (activate) the newly created 310 The "periodic_ns" variant doesn't start (activate) the newly created
263 watcher. 311 watcher.
264 312
265 $w->set ($at, $interval) 313 $w->set ($at, $interval, $reschedule_cb)
266 Reconfigures the watcher, see the constructor above for details. Can 314 Reconfigures the watcher, see the constructor above for details. Can
267 be at any time. 315 be at any time.
316
317 $w->again
318 Simply stops and starts the watcher again.
268 319
269 $w = EV::signal $signal, $callback 320 $w = EV::signal $signal, $callback
270 $w = EV::signal_ns $signal, $callback 321 $w = EV::signal_ns $signal, $callback
271 Call the callback when $signal is received (the signal can be 322 Call the callback when $signal is received (the signal can be
272 specified by number or by name, just as with kill or %SIG). 323 specified by number or by name, just as with kill or %SIG).

Diff Legend

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