<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Periodic watcher operation modes</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="ev.watcher-callbacks.html">Watcher callbacks</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.ev.html">Ev</a></div>
<div class="up"><a href="book.ev.html">Ev</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="ev.periodic-modes" class="chapter">
<h1>Periodic watcher operation modes</h1>
<p class="para">
<a href="class.evperiodic.html" class="classname">EvPeriodic</a>
watcher works in different modes depending on the
<em><code class="parameter">offset</code></em>
,
<em><code class="parameter">interval</code></em>
and
<em><code class="parameter">reschedule_cb</code></em>
parameters.
</p>
<ol type="1">
<li class="listitem">
<p class="para">
<em class="emphasis">Absolute timer</em>
. In this mode
<em><code class="parameter">interval</code></em>
=
<strong><code>0</code></strong>
,
<em><code class="parameter">reschedule_cb</code></em>
= <strong><code>NULL</code></strong>. This time simply fires at the wallclock time
<em><code class="parameter">offset</code></em>
and doesn't repeat. It will not adjust when a time jump occurs, that is,
if it is to be run at
<em class="emphasis">January
1st 2014</em>
then it will run when the system time reaches or surpasses this time.
</p>
</li>
<li class="listitem">
<p class="para">
<em class="emphasis">Repeating interval timer</em>
. In this mode
<em><code class="parameter">interval</code></em>
>
<strong><code>0</code></strong>
,
<em><code class="parameter">reschedule_cb</code></em>
= <strong><code>NULL</code></strong>; the watcher will always be scheduled to timeout at the next
<em><code class="parameter">offset</code></em>
+
<strong><code>N</code></strong>
*
<em><code class="parameter">interval</code></em>
time(for some integer
<strong><code>N</code></strong>
) and then repeat, regardless of any time jumps.
</p>
<p class="para">
This can be used to create timers that do not drift with respect to system
time:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$hourly </span><span style="color: #007700">= </span><span style="color: #0000BB">EvPeriodic</span><span style="color: #007700">(</span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #0000BB">3600</span><span style="color: #007700">, </span><span style="color: #0000BB">NULL</span><span style="color: #007700">, function () {<br /> echo </span><span style="color: #DD0000">"once per hour\n"</span><span style="color: #007700">;<br />};<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
That doesn't mean there will always be
<strong><code>3600</code></strong>
seconds in between triggers, but only that the the callback will be called
when the system time shows a full hour(
<em class="emphasis">UTC</em>
).
</p>
<p class="para">
<a href="class.evperiodic.html" class="classname">EvPeriodic</a>
will try to run the callback in this mode at the next possible time where
<var class="varname"><var class="varname">time</var></var>
=
<em><code class="parameter">offset</code></em>
(
<em>mod</em>
<em><code class="parameter">interval</code></em>
), regardless of any time jumps.
</p>
</li>
<li class="listitem">
<p class="para">
<em class="emphasis">Manual reschedule mode</em>
. In this mode
<em><code class="parameter">reschedule_cb</code></em>
is a
<span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span>
.
</p>
<p class="para">
<em><code class="parameter">interval</code></em>
and
<em><code class="parameter">offset</code></em>
are both being ignored. Instead, each time the periodic watcher gets
scheduled, the reschedule callback (
<em><code class="parameter">reschedule_cb</code></em>
) will be called with the watcher as first, and the current time as second
argument.
</p>
<p class="para">
This callback
<em class="emphasis">must not</em>
stop or destroy this or any other periodic watchers, ever, and
<em class="emphasis">must not</em>
call any event loop functions or methods. To stop it return
<strong><code>1e30</code></strong>
and stop it afterwards. An
<a href="class.evprepare.html" class="classname">EvPrepare</a>
watcher may be used for this task.
</p>
<p class="para">
It must return the next time to trigger, based on the passed time value
(that is, the lowest time value larger than or equal to to the second
argument). It will usually be called just before the callback will be
triggered, but might be called at other times, too.
</p>
<div class="example" id="example-3622">
<p><strong>Example #1 Using reschedule callback</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// Tick each 10.5 seconds<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">reschedule_cb </span><span style="color: #007700">(</span><span style="color: #0000BB">$watcher</span><span style="color: #007700">, </span><span style="color: #0000BB">$now</span><span style="color: #007700">) {<br /> return </span><span style="color: #0000BB">$now </span><span style="color: #007700">+ (</span><span style="color: #0000BB">10.5</span><span style="color: #007700">. - </span><span style="color: #0000BB">fmod</span><span style="color: #007700">(</span><span style="color: #0000BB">$now</span><span style="color: #007700">, </span><span style="color: #0000BB">10.5</span><span style="color: #007700">));<br />}<br /><br /></span><span style="color: #0000BB">$w </span><span style="color: #007700">= new </span><span style="color: #0000BB">EvPeriodic</span><span style="color: #007700">(</span><span style="color: #0000BB">0.</span><span style="color: #007700">, </span><span style="color: #0000BB">0.</span><span style="color: #007700">, </span><span style="color: #DD0000">"reschedule_cb"</span><span style="color: #007700">, function (</span><span style="color: #0000BB">$w</span><span style="color: #007700">, </span><span style="color: #0000BB">$revents</span><span style="color: #007700">) {<br /> echo </span><span style="color: #0000BB">time</span><span style="color: #007700">(), </span><span style="color: #0000BB">PHP_EOL</span><span style="color: #007700">;<br />});<br /><br /></span><span style="color: #0000BB">Ev</span><span style="color: #007700">::</span><span style="color: #0000BB">run</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</li>
</ol>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="ev.watcher-callbacks.html">Watcher callbacks</a></div>
<div class="next" style="text-align: right; float: right;"><a href="class.ev.html">Ev</a></div>
<div class="up"><a href="book.ev.html">Ev</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
