diff options
| -rw-r--r-- | ev.html | 30 | ||||
| -rw-r--r-- | ev.pod | 30 |
2 files changed, 41 insertions, 19 deletions
@@ -6,7 +6,7 @@ <meta name="description" content="Pod documentation for libev" /> <meta name="inputfile" content="<standard input>" /> <meta name="outputfile" content="<standard output>" /> - <meta name="created" content="Sat Dec 8 23:11:11 2007" /> + <meta name="created" content="Sun Dec 9 20:30:11 2007" /> <meta name="generator" content="Pod::Xhtml 1.57" /> <link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head> <body> @@ -1099,10 +1099,10 @@ to trigger "at" some specific point in time. For example, if you tell periodic watcher to trigger in 10 seconds (by specifiying e.g. <code>ev_now () + 10.</code>) and then reset your system clock to the last year, then it will take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger -roughly 10 seconds later and of course not if you reset your system time -again).</p> +roughly 10 seconds later).</p> <p>They can also be used to implement vastly more complex timers, such as -triggering an event on eahc midnight, local time.</p> +triggering an event on each midnight, local time or other, complicated, +rules.</p> <p>As with timers, the callback is guarenteed to be invoked only when the time (<code>at</code>) has been passed, but if multiple periodic timers become ready during the same loop iteration then order of execution is undefined.</p> @@ -1114,18 +1114,18 @@ during the same loop iteration then order of execution is undefined.</p> operation, and we will explain them from simplest to complex:</p> <p> <dl> - <dt>* absolute timer (interval = reschedule_cb = 0)</dt> + <dt>* absolute timer (at = time, interval = reschedule_cb = 0)</dt> <dd> <p>In this configuration the watcher triggers an event at the wallclock time <code>at</code> and doesn't repeat. It will not adjust when a time jump occurs, that is, if it is to be run at January 1st 2011 then it will run when the system time reaches or surpasses this time.</p> </dd> - <dt>* non-repeating interval timer (interval > 0, reschedule_cb = 0)</dt> + <dt>* non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)</dt> <dd> <p>In this mode the watcher will always be scheduled to time out at the next -<code>at + N * interval</code> time (for some integer N) and then repeat, regardless -of any time jumps.</p> +<code>at + N * interval</code> time (for some integer N, which can also be negative) +and then repeat, regardless of any time jumps.</p> <p>This can be used to create timers that do not drift with respect to system time:</p> <pre> ev_periodic_set (&periodic, 0., 3600., 0); @@ -1138,8 +1138,11 @@ by 3600.</p> <p>Another way to think about it (for the mathematically inclined) is that <code>ev_periodic</code> will try to run the callback in this mode at the next possible time where <code>time = at (mod interval)</code>, regardless of any time jumps.</p> + <p>For numerical stability it is preferable that the <code>at</code> value is near +<code>ev_now ()</code> (the current time), but there is no range requirement for +this value.</p> </dd> - <dt>* manual reschedule mode (reschedule_cb = callback)</dt> + <dt>* manual reschedule mode (at and interval ignored, reschedule_cb = callback)</dt> <dd> <p>In this mode the values for <code>interval</code> and <code>at</code> are both being ignored. Instead, each time the periodic watcher gets scheduled, the @@ -1148,7 +1151,7 @@ current time as second argument.</p> <p>NOTE: <i>This callback MUST NOT stop or destroy any periodic watcher, ever, or make any event loop modifications</i>. If you need to stop it, return <code>now + 1e30</code> (or so, fudge fudge) and stop it afterwards (e.g. by -starting a prepare watcher).</p> +starting an <code>ev_prepare</code> watcher, which is legal).</p> <p>Its prototype is <code>ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now)</code>, e.g.:</p> <pre> static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) @@ -1179,6 +1182,13 @@ when you changed some parameters or the reschedule callback would return a different time than the last time it was called (e.g. in a crond like program when the crontabs have changed).</p> </dd> + <dt>ev_tstamp offset [read-write]</dt> + <dd> + <p>When repeating, this contains the offset value, otherwise this is the +absolute point in time (the <code>at</code> value passed to <code>ev_periodic_set</code>).</p> + <p>Can be modified any time, but changes only take effect when the periodic +timer fires or <code>ev_periodic_again</code> is being called.</p> + </dd> <dt>ev_tstamp interval [read-write]</dt> <dd> <p>The current interval value. Can be modified any time, but changes only @@ -1076,11 +1076,11 @@ to trigger "at" some specific point in time. For example, if you tell a periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () + 10.>) and then reset your system clock to the last year, then it will take a year to trigger the event (unlike an C<ev_timer>, which would trigger -roughly 10 seconds later and of course not if you reset your system time -again). +roughly 10 seconds later). They can also be used to implement vastly more complex timers, such as -triggering an event on eahc midnight, local time. +triggering an event on each midnight, local time or other, complicated, +rules. As with timers, the callback is guarenteed to be invoked only when the time (C<at>) has been passed, but if multiple periodic timers become ready @@ -1097,18 +1097,18 @@ operation, and we will explain them from simplest to complex: =over 4 -=item * absolute timer (interval = reschedule_cb = 0) +=item * absolute timer (at = time, interval = reschedule_cb = 0) In this configuration the watcher triggers an event at the wallclock time C<at> and doesn't repeat. It will not adjust when a time jump occurs, that is, if it is to be run at January 1st 2011 then it will run when the system time reaches or surpasses this time. -=item * non-repeating interval timer (interval > 0, reschedule_cb = 0) +=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) In this mode the watcher will always be scheduled to time out at the next -C<at + N * interval> time (for some integer N) and then repeat, regardless -of any time jumps. +C<at + N * interval> time (for some integer N, which can also be negative) +and then repeat, regardless of any time jumps. This can be used to create timers that do not drift with respect to system time: @@ -1124,7 +1124,11 @@ Another way to think about it (for the mathematically inclined) is that C<ev_periodic> will try to run the callback in this mode at the next possible time where C<time = at (mod interval)>, regardless of any time jumps. -=item * manual reschedule mode (reschedule_cb = callback) +For numerical stability it is preferable that the C<at> value is near +C<ev_now ()> (the current time), but there is no range requirement for +this value. + +=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) In this mode the values for C<interval> and C<at> are both being ignored. Instead, each time the periodic watcher gets scheduled, the @@ -1134,7 +1138,7 @@ current time as second argument. NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, ever, or make any event loop modifications>. If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by -starting a prepare watcher). +starting an C<ev_prepare> watcher, which is legal). Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now)>, e.g.: @@ -1167,6 +1171,14 @@ when you changed some parameters or the reschedule callback would return a different time than the last time it was called (e.g. in a crond like program when the crontabs have changed). +=item ev_tstamp offset [read-write] + +When repeating, this contains the offset value, otherwise this is the +absolute point in time (the C<at> value passed to C<ev_periodic_set>). + +Can be modified any time, but changes only take effect when the periodic +timer fires or C<ev_periodic_again> is being called. + =item ev_tstamp interval [read-write] The current interval value. Can be modified any time, but changes only |