1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 328943 $ -->
<chapter xml:id="ev.periodic-modes" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Periodic watcher operation modes</title>
<para>
<classname>EvPeriodic</classname>
watcher works in different modes depending on the
<parameter>offset</parameter>
,
<parameter>interval</parameter>
and
<parameter>reschedule_cb</parameter>
parameters.
</para>
<orderedlist>
<listitem>
<para>
<emphasis>Absolute timer</emphasis>
. In this mode
<parameter>interval</parameter>
=
<constant>0</constant>
,
<parameter>reschedule_cb</parameter>
= &null;. This time simply fires at the wallclock time
<parameter>offset</parameter>
and doesn't repeat. It will not adjust when a time jump occurs, that is,
if it is to be run at
<emphasis>January
1st 2014</emphasis>
then it will run when the system time reaches or surpasses this time.
</para>
</listitem>
<listitem>
<para>
<emphasis>Repeating interval timer</emphasis>
. In this mode
<parameter>interval</parameter>
>
<constant>0</constant>
,
<parameter>reschedule_cb</parameter>
= &null;; the watcher will always be scheduled to timeout at the next
<parameter>offset</parameter>
+
<constant>N</constant>
*
<parameter>interval</parameter>
time(for some integer
<constant>N</constant>
) and then repeat, regardless of any time jumps.
</para>
<para>
This can be used to create timers that do not drift with respect to system
time:
<programlisting role="php">
<![CDATA[
<?php
$hourly = EvPeriodic(0, 3600, NULL, function () {
echo "once per hour\n";
};
?>
]]>
</programlisting>
That doesn't mean there will always be
<constant>3600</constant>
seconds in between triggers, but only that the the callback will be called
when the system time shows a full hour(
<emphasis>UTC</emphasis>
).
</para>
<para>
<classname>EvPeriodic</classname>
will try to run the callback in this mode at the next possible time where
<varname>time</varname>
=
<parameter>offset</parameter>
(
<literal>mod</literal>
<parameter>interval</parameter>
), regardless of any time jumps.
</para>
</listitem>
<listitem>
<para>
<emphasis>Manual reschedule mode</emphasis>
. In this mode
<parameter>reschedule_cb</parameter>
is a
<type>callable</type>
.
</para>
<para>
<parameter>interval</parameter>
and
<parameter>offset</parameter>
are both being ignored. Instead, each time the periodic watcher gets
scheduled, the reschedule callback (
<parameter>reschedule_cb</parameter>
) will be called with the watcher as first, and the current time as second
argument.
</para>
<para>
This callback
<emphasis>must not</emphasis>
stop or destroy this or any other periodic watchers, ever, and
<emphasis>must not</emphasis>
call any event loop functions or methods. To stop it return
<constant>1e30</constant>
and stop it afterwards. An
<classname>EvPrepare</classname>
watcher may be used for this task.
</para>
<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.
</para>
<example>
<title>Using reschedule callback</title>
<programlisting role="php">
<![CDATA[
<?php
// Tick each 10.5 seconds
function reschedule_cb ($watcher, $now) {
return $now + (10.5. - fmod($now, 10.5));
}
$w = new EvPeriodic(0., 0., "reschedule_cb", function ($w, $revents) {
echo time(), PHP_EOL;
});
Ev::run();
?>
]]>
</programlisting>
</example>
</listitem>
</orderedlist>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
