Skip to content

Commit 6f23e82

Browse files
NathanFreemanNathanFreeman
committed
optimize swoole timer
1 parent 09324fb commit 6f23e82

File tree

9 files changed

+384
-54
lines changed

9 files changed

+384
-54
lines changed

‎reference/swoole/swoole.timer.xml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,58 @@
1212
<section xml:id="swoole-timer.intro">
1313
&reftitle.intro;
1414
<para>
15+
Millisecond precision timer. The underlying implementation is based on epoll_wait and setitimer,
16+
using a min-heap data structure that supports adding a large number of timers.
17+
</para>
18+
<para>
19+
In synchronous IO processes, it's implemented using setitimer and signals, such as in Manager and TaskWorker processes.
20+
</para>
21+
<para>
22+
In asynchronous IO processes, it's implemented using the timeout of epoll_wait/kevent/poll/select.
23+
</para>
24+
<para>
25+
The underlying system does not support timers with a time parameter of 0. This is different from languages like Node.js.
26+
In Swoole, you can use Swoole\Event::defer to achieve similar functionality.
27+
<programlisting role="php">
28+
<![CDATA[
29+
<?php
30+
Swoole\Event::defer(function () {
31+
echo "hello\n";
32+
});
33+
?>
34+
]]>
35+
</programlisting>
36+
</para>
37+
<para>
38+
Timer Correction: The execution time of the timer callback function does not affect the timing of the
39+
next timer execution. For example, setting a tick timer of 10ms after 0.002s, the first callback will
40+
be executed at 0.012s, if the callback function takes 5ms to execute, the next timer will still trigger
41+
at 0.022s, not at 0.027s.
1542

43+
However, if the execution time of the timer callback function is too long, even covering the time of the
44+
next timer execution, the underlying system will perform time correction, discarding the expired behavior
45+
and triggering the timer callback at the next available time. For example, if the callback function
46+
at 0.012s takes 15ms to execute, causing the timer at 0.022s to be delayed, the timer callback
47+
will be triggered again at 0.032s.
48+
</para>
49+
<para>
50+
By default, when a timer is triggered, a coroutine is automatically created to execute the callback function.
1651
</para>
52+
<warning>
53+
<simpara>
54+
Timer only works within the current process space.
55+
</simpara>
56+
</warning>
57+
<warning>
58+
<simpara>
59+
Timer is purely asynchronous and incompatible with synchronous IO functions.
60+
</simpara>
61+
</warning>
62+
<warning>
63+
<simpara>
64+
Timer execution may experience minor timing deviations.
65+
</simpara>
66+
</warning>
1767
</section>
1868
<!-- }}} -->
1969

‎reference/swoole/swoole/timer/after.xml‎

Lines changed: 38 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,38 +4,47 @@
44
<refentry xml:id="swoole-timer.after" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
55
<refnamediv>
66
<refname>Swoole\Timer::after</refname>
7-
<refpurpose>Trigger a callback function after a period of time.</refpurpose>
7+
<refpurpose>Execute a function after specified time.</refpurpose>
88
</refnamediv>
99

1010
<refsect1 role="description">
1111
&reftitle.description;
1212
<methodsynopsis>
13-
<modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Timer::after</methodname>
14-
<methodparam><type>int</type><parameter>after_time_ms</parameter></methodparam>
15-
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
13+
<modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>Swoole\Timer::after</methodname>
14+
<methodparam><type>int</type><parameter>msec</parameter></methodparam>
15+
<methodparam><type>callable</type><parameter>callback_function</parameter></methodparam>
16+
<methodparam rep="repeat"><type>mixed</type><parameter>params</parameter></methodparam>
1617
</methodsynopsis>
1718
<para>
18-
Trigger a callback function after a period of time.
19+
Execute a function after a specified time. The Swoole\Timer::after function is a one-time timer that will be
20+
destroyed once executed.
1921
</para>
20-
2122
</refsect1>
2223

2324
<refsect1 role="parameters">
2425
&reftitle.parameters;
2526
<variablelist>
2627
<varlistentry>
27-
<term><parameter>after_time_ms</parameter></term>
28+
<term><parameter>msec</parameter></term>
2829
<listitem>
2930
<para>
30-
31+
Specified time in milliseconds (e.g. 1000 means 1 second).
3132
</para>
3233
</listitem>
3334
</varlistentry>
3435
<varlistentry>
35-
<term><parameter>callback</parameter></term>
36+
<term><parameter>callback_function</parameter></term>
3637
<listitem>
3738
<para>
38-
39+
The callback function to be executed when timer expires.
40+
</para>
41+
</listitem>
42+
</varlistentry>
43+
<varlistentry>
44+
<term><parameter>params</parameter></term>
45+
<listitem>
46+
<para>
47+
Additional parameters to pass to the callback function.
3948
</para>
4049
</listitem>
4150
</varlistentry>
@@ -45,11 +54,28 @@
4554
<refsect1 role="returnvalues">
4655
&reftitle.returnvalues;
4756
<para>
48-
57+
Returns timer ID which can be used to clear the timer.
4958
</para>
5059
</refsect1>
5160

52-
61+
<refsect1 role="examples">
62+
&reftitle.examples;
63+
<para>
64+
<example>
65+
<title><function>Swoole\Timer::after</function> example</title>
66+
<programlisting role="php">
67+
<![CDATA[
68+
<?php
69+
$str = "Swoole";
70+
Swoole\Timer::after(1000, function() use ($str) {
71+
echo "Hello, $str\n";
72+
});
73+
?>
74+
]]>
75+
</programlisting>
76+
</example>
77+
</para>
78+
</refsect1>
5379
</refentry>
5480

5581
<!-- Keep this comment at the end of the file

‎reference/swoole/swoole/timer/clear.xml‎

Lines changed: 16 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,43 +4,42 @@
44
<refentry xml:id="swoole-timer.clear" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
55
<refnamediv>
66
<refname>Swoole\Timer::clear</refname>
7-
<refpurpose>Delete a timer by timer ID.</refpurpose>
7+
<refpurpose>Clear a timer by ID</refpurpose>
88
</refnamediv>
99

1010
<refsect1 role="description">
1111
&reftitle.description;
1212
<methodsynopsis>
13-
<modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>Swoole\Timer::clear</methodname>
13+
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Timer::clear</methodname>
1414
<methodparam><type>int</type><parameter>timer_id</parameter></methodparam>
1515
</methodsynopsis>
1616
<para>
17-
Delete a timer by timer ID.
17+
Use timer ID to delete a timer. Cannot be used to clear timers from other processes.
1818
</para>
19-
2019
</refsect1>
2120

2221
<refsect1 role="parameters">
2322
&reftitle.parameters;
24-
<variablelist>
25-
<varlistentry>
26-
<term><parameter>timer_id</parameter></term>
27-
<listitem>
28-
<para>
29-
30-
</para>
31-
</listitem>
32-
</varlistentry>
33-
</variablelist>
23+
<para>
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>timer_id</parameter></term>
27+
<listitem>
28+
<para>
29+
The timer ID returned by Timer::tick or Timer::after.
30+
</para>
31+
</listitem>
32+
</varlistentry>
33+
</variablelist>
34+
</para>
3435
</refsect1>
3536

3637
<refsect1 role="returnvalues">
3738
&reftitle.returnvalues;
3839
<para>
39-
40+
&return.success;
4041
</para>
4142
</refsect1>
42-
43-
4443
</refentry>
4544

4645
<!-- Keep this comment at the end of the file

‎reference/swoole/swoole/timer/clearAll.xml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<refentry xml:id="swoole-timer.clearall" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>Swoole\Timer::clearAll</refname>
7+
<refpurpose>Clear all timers in current worker process.</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Timer::clearAll</methodname>
14+
<void/>
15+
</methodsynopsis>
16+
<para>
17+
Clear all timers in current worker process. Available since Swoole version >= v4.4.0.
18+
</para>
19+
</refsect1>
20+
21+
<refsect1 role="returnvalues">
22+
&reftitle.returnvalues;
23+
<para>
24+
&return.success;
25+
</para>
26+
</refsect1>
27+
</refentry>
28+
29+
<!-- Keep this comment at the end of the file
30+
Local variables:
31+
mode: sgml
32+
sgml-omittag:t
33+
sgml-shorttag:t
34+
sgml-minimize-attributes:nil
35+
sgml-always-quote-attributes:t
36+
sgml-indent-step:1
37+
sgml-indent-data:t
38+
indent-tabs-mode:nil
39+
sgml-parent-document:nil
40+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
41+
sgml-exposed-tags:nil
42+
sgml-local-catalogs:nil
43+
sgml-local-ecat-files:nil
44+
End:
45+
vim600: syn=xml fen fdm=syntax fdl=2 si
46+
vim: et tw=78 syn=sgml
47+
vi: ts=1 sw=1
48+
-->

‎reference/swoole/swoole/timer/exists.xml‎ renamed to ‎reference/swoole/swoole/timer/info.xml‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,21 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
33

4-
<refentry xml:id="swoole-timer.exists" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<refentry xml:id="swoole-timer.info" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
55
<refnamediv>
6-
<refname>Swoole\Timer::exists</refname>
7-
<refpurpose>Check if a timer is existed.</refpurpose>
6+
<refname>Swoole\Timer::info</refname>
7+
<refpurpose>Get information about a timer.</refpurpose>
88
</refnamediv>
99

1010
<refsect1 role="description">
1111
&reftitle.description;
1212
<methodsynopsis>
13-
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Swoole\Timer::exists</methodname>
13+
<modifier>public</modifier> <modifier>static</modifier> <type>array</type><methodname>Swoole\Timer::info</methodname>
1414
<methodparam><type>int</type><parameter>timer_id</parameter></methodparam>
1515
</methodsynopsis>
1616
<para>
17-
Check if a timer is existed.
17+
Get information about a timer. Available since Swoole version >= v4.4.0.
1818
</para>
19-
2019
</refsect1>
2120

2221
<refsect1 role="parameters">
@@ -26,7 +25,7 @@
2625
<term><parameter>timer_id</parameter></term>
2726
<listitem>
2827
<para>
29-
28+
The timer ID
3029
</para>
3130
</listitem>
3231
</varlistentry>
@@ -36,11 +35,18 @@
3635
<refsect1 role="returnvalues">
3736
&reftitle.returnvalues;
3837
<para>
39-
38+
Returns an array with timer information:
39+
<![CDATA[
40+
array(5) {
41+
["exec_msec"]=> int(6000)
42+
["exec_count"]=> int(5)
43+
["interval"]=> int(1000)
44+
["round"]=> int(0)
45+
["removed"]=> bool(false)
46+
}
47+
]]>
4048
</para>
4149
</refsect1>
42-
43-
4450
</refentry>
4551

4652
<!-- Keep this comment at the end of the file

‎reference/swoole/swoole/timer/list.xml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<refentry xml:id="swoole-timer.list" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>Swoole\Timer::list</refname>
7+
<refpurpose>Get iterator for all timers in current worker process.</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<methodsynopsis>
13+
<modifier>public</modifier> <modifier>static</modifier> <type>Swoole\Timer\Iterator</type><methodname>Swoole\Timer::list</methodname>
14+
<void/>
15+
</methodsynopsis>
16+
<para>
17+
Returns timer iterator which can be used to traverse all timer IDs in current worker process.
18+
</para>
19+
</refsect1>
20+
21+
<refsect1 role="returnvalues">
22+
&reftitle.returnvalues;
23+
<para>
24+
Returns Swoole\Timer\Iterator object.
25+
</para>
26+
</refsect1>
27+
28+
<refsect1 role="examples">
29+
&reftitle.examples;
30+
<para>
31+
<example>
32+
<title><function>Swoole\Timer::list</function> example</title>
33+
<programlisting role="php">
34+
<![CDATA[
35+
<?php
36+
foreach (Swoole\Timer::list() as $timer_id) {
37+
var_dump(Swoole\Timer::info($timer_id));
38+
}
39+
?>
40+
]]>
41+
</programlisting>
42+
</example>
43+
</para>
44+
</refsect1>
45+
</refentry>
46+
47+
<!-- Keep this comment at the end of the file
48+
Local variables:
49+
mode: sgml
50+
sgml-omittag:t
51+
sgml-shorttag:t
52+
sgml-minimize-attributes:nil
53+
sgml-always-quote-attributes:t
54+
sgml-indent-step:1
55+
sgml-indent-data:t
56+
indent-tabs-mode:nil
57+
sgml-parent-document:nil
58+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
59+
sgml-exposed-tags:nil
60+
sgml-local-catalogs:nil
61+
sgml-local-ecat-files:nil
62+
End:
63+
vim600: syn=xml fen fdm=syntax fdl=2 si
64+
vim: et tw=78 syn=sgml
65+
vi: ts=1 sw=1
66+
-->

0 commit comments

Comments
 (0)