[doc-en] master: optimize swoole timer docs (#4773)
| From: | MARiA so cute via GitHub | Date: | Wed, 02 Sep 2026 13:38:57 +0000 |
| Subject: | [doc-en] master: optimize swoole timer docs (#4773) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23699@lists.php.net to get a copy of this message | ||
Author: MARiA so cute (NathanFreeman)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-09-02T15:38:54+02:00
Commit: https://github.com/php/doc-en/commit/6e77169fdc9c087749f357bef877607ccc05f442
Raw diff: https://github.com/php/doc-en/commit/6e77169fdc9c087749f357bef877607ccc05f442.diff
optimize swoole timer docs (#4773)
* optimize swoole timer
* Few nits
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
* Apply suggestions from code review
Co-authored-by: Luffy <lufei@apache.org>
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
* swoole: restore Timer::exists and correct the timer documentation
Timer::exists() is still part of Swoole; its page was reused for
Timer::set(), which was deprecated in 4.6.0 and removed in 6.0.0.
Also: name Timer::set()'s parameter settings, document the array keys of
info() and stats(), the timer id passed to tick() callbacks, the failure
paths of tick()/after()/clear()/clearAll(), and fix the var_dump output
blocks, a CRLF line ending and the merged simpara in the intro.
---------
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
Co-authored-by: Luffy <lufei@apache.org>
Changed paths:
A reference/swoole/swoole/timer/clearAll.xml
A reference/swoole/swoole/timer/info.xml
A reference/swoole/swoole/timer/list.xml
A reference/swoole/swoole/timer/set.xml
A reference/swoole/swoole/timer/stats.xml
M reference/swoole/swoole.timer.xml
M reference/swoole/swoole/timer/after.xml
M reference/swoole/swoole/timer/clear.xml
M reference/swoole/swoole/timer/exists.xml
M reference/swoole/swoole/timer/tick.xml
Diff:
diff --git a/reference/swoole/swoole.timer.xml b/reference/swoole/swoole.timer.xml
index 035a6093c494..d39a63a9bda6 100644
--- a/reference/swoole/swoole.timer.xml
+++ b/reference/swoole/swoole.timer.xml
@@ -11,9 +11,68 @@
<!-- {{{ Swoole\Timer intro -->
<section xml:id="swoole-timer.intro">
&reftitle.intro;
+ <simpara>
+ Millisecond precision timer. The underlying implementation is based on epoll_wait and
setitimer,
+ using a min-heap data structure that supports adding a large number of timers.
+ </simpara>
+ <simpara>
+ In synchronous I/O processes, such as the Manager and TaskWorker processes, it is
+ implemented using setitimer and signals.
+ </simpara>
+ <simpara>
+ In asynchronous I/O processes, it is implemented using the timeout of
+ epoll_wait/kevent/poll/select.
+ </simpara>
<para>
-
+ The underlying system does not support timers with a delay of <literal>0</literal>;
+ values below <literal>1</literal> millisecond emit an
+ <constant>E_WARNING</constant> and the call fails. This differs from
+ languages such as Node.js.
+ <methodname linkend="swoole-event.defer">Swoole\Event::defer</methodname>
+ may be used to achieve similar functionality.
+ <programlisting role="php">
+<![CDATA[
+<?php
+Swoole\Event::defer(function () {
+ echo "hello\n";
+});
+?>
+]]>
+ </programlisting>
</para>
+ <simpara>
+ Timer Correction: The execution time of the timer callback function does not affect the timing
of the
+ next timer execution. For example, setting a tick timer of 10ms after 0.002s, the first
callback will
+ be executed at 0.012s, if the callback function takes 5ms to execute, the next timer will still
trigger
+ at 0.022s, not at 0.027s.
+ </simpara>
+ <simpara>
+ However, if the execution time of the timer callback function is too long, even covering the
time of the
+ next timer execution, the underlying system will perform time correction, discarding the
expired behavior
+ and triggering the timer callback at the next available time. For example, if the callback
function
+ at 0.012s takes 15ms to execute, causing the timer at 0.022s to be delayed, the timer callback
+ will be triggered again at 0.032s.
+ </simpara>
+ <simpara>
+ By default, when a timer is triggered, a coroutine is automatically created
+ to execute the callback function. This can be disabled with
+ <function>swoole_async_set</function>.
+ </simpara>
+ <warning>
+ <simpara>
+ Timer only works within the current process space.
+ </simpara>
+ </warning>
+ <warning>
+ <simpara>
+ Timer is purely asynchronous and incompatible with synchronous I/O functions.
+ </simpara>
+ </warning>
+ <warning>
+ <simpara>
+ Timer execution may experience minor timing deviations.
+ </simpara>
+ </warning>
</section>
<!-- }}} -->
diff --git a/reference/swoole/swoole/timer/after.xml b/reference/swoole/swoole/timer/after.xml
index 6aa828e536f0..7cb5d35b9a53 100644
--- a/reference/swoole/swoole/timer/after.xml
+++ b/reference/swoole/swoole/timer/after.xml
@@ -4,39 +4,53 @@
<refentry xml:id="swoole-timer.after" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Timer::after</refname>
- <refpurpose>Trigger a callback function after a period of time.</refpurpose>
+ <refpurpose>Execute a function after a specified time</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <modifier>public</modifier> <modifier>static</modifier>
<type>void</type><methodname>Swoole\Timer::after</methodname>
-
<methodparam><type>int</type><parameter>after_time_ms</parameter></methodparam>
+ <modifier>public</modifier> <modifier>static</modifier> <type
class="union"><type>int</type><type>false</type></type><methodname>Swoole\Timer::after</methodname>
+
<methodparam><type>int</type><parameter>ms</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
+ <methodparam
rep="repeat"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
- <para>
- Trigger a callback function after a period of time.
- </para>
-
+ <simpara>
+ Creates a one-shot timer, which is destroyed once its callback has run.
+ Unlike <function>sleep</function>, it does not block the current process.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>after_time_ms</parameter></term>
+ <term><parameter>ms</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ The delay in milliseconds. Must be greater than or equal to
+ <literal>1</literal>; a lower value emits an
<constant>E_WARNING</constant>
+ and the call fails.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ The function to execute once the delay has elapsed. It is called as
+ <literal>callback(mixed ...$params)</literal>. Unlike
+ <methodname>Swoole\Timer::tick</methodname>, the timer ID is not passed
+ to the callback.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>params</parameter></term>
+ <listitem>
+ <simpara>
+ Additional values passed to <parameter>callback</parameter>.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -44,12 +58,35 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
-
- </para>
+ <simpara>
+ Returns the timer ID, which can be passed to
+ <methodname>Swoole\Timer::clear</methodname> to cancel the timer before it
+ fires. Returns &false; if the timer could not be created, in particular when
+ <parameter>ms</parameter> is less than <literal>1</literal>.
+ </simpara>
</refsect1>
-
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>Swoole\Timer::after</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+Swoole\Timer::after(1000, function (string $name) {
+ echo "Hello, $name\n";
+}, "Swoole");
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Hello, Swoole
+]]>
+ </screen>
+ </example>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/swoole/swoole/timer/clear.xml b/reference/swoole/swoole/timer/clear.xml
index 7212a5a81ad2..6ab179db4093 100644
--- a/reference/swoole/swoole/timer/clear.xml
+++ b/reference/swoole/swoole/timer/clear.xml
@@ -4,19 +4,20 @@
<refentry xml:id="swoole-timer.clear" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Timer::clear</refname>
- <refpurpose>Delete a timer by timer ID.</refpurpose>
+ <refpurpose>Delete a timer by ID</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <modifier>public</modifier> <modifier>static</modifier>
<type>void</type><methodname>Swoole\Timer::clear</methodname>
+ <modifier>public</modifier> <modifier>static</modifier>
<type>bool</type><methodname>Swoole\Timer::clear</methodname>
<methodparam><type>int</type><parameter>timer_id</parameter></methodparam>
</methodsynopsis>
- <para>
- Delete a timer by timer ID.
- </para>
-
+ <simpara>
+ Deletes the timer with the given ID. Only timers created by the current
+ process can be removed; timers belonging to other processes are not visible
+ here.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -25,9 +26,10 @@
<varlistentry>
<term><parameter>timer_id</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ The timer ID returned by <methodname>Swoole\Timer::tick</methodname> or
+ <methodname>Swoole\Timer::after</methodname>.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -35,12 +37,35 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
-
- </para>
+ <simpara>
+ &return.success;
+ &false; is returned when no timer with this ID exists in the current
+ process, or when the ID refers to an internal timer.
+ </simpara>
</refsect1>
-
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>Swoole\Timer::clear</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timer_id = Swoole\Timer::after(1000, function () {
+ echo "never printed\n";
+});
+var_dump(Swoole\Timer::clear($timer_id));
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+bool(true)
+]]>
+ </screen>
+ </example>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/swoole/swoole/timer/clearAll.xml b/reference/swoole/swoole/timer/clearAll.xml
new file mode 100644
index 000000000000..72a72ed81618
--- /dev/null
+++ b/reference/swoole/swoole/timer/clearAll.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-timer.clearall" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>Swoole\Timer::clearAll</refname>
+ <refpurpose>Clear all timers in the current process.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <modifier>public</modifier> <modifier>static</modifier>
<type>bool</type><methodname>Swoole\Timer::clearAll</methodname>
+ <void/>
+ </methodsynopsis>
+ <simpara>
+ Clear all timers in the current process. As of Swoole 4.4.0.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ &return.success;
+ &false; is returned when no timer has been created in this process yet.
+ Only timers created from PHP are removed; internal timers are left in place.
+ </simpara>
+ </refsect1>
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/swoole/swoole/timer/exists.xml b/reference/swoole/swoole/timer/exists.xml
index 50fd227fbf63..9513c8192772 100644
--- a/reference/swoole/swoole/timer/exists.xml
+++ b/reference/swoole/swoole/timer/exists.xml
@@ -13,9 +13,9 @@
<modifier>public</modifier> <modifier>static</modifier>
<type>bool</type><methodname>Swoole\Timer::exists</methodname>
<methodparam><type>int</type><parameter>timer_id</parameter></methodparam>
</methodsynopsis>
- <para>
- Check if a timer is existed.
- </para>
+ <simpara>
+ Checks whether a timer with the given ID exists in the current process.
+ </simpara>
</refsect1>
@@ -25,9 +25,10 @@
<varlistentry>
<term><parameter>timer_id</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ The timer ID returned by <methodname>Swoole\Timer::tick</methodname> or
+ <methodname>Swoole\Timer::after</methodname>.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -35,9 +36,10 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
-
- </para>
+ <simpara>
+ Returns &true; if a timer with this ID exists in the current process,
+ &false; otherwise.
+ </simpara>
</refsect1>
diff --git a/reference/swoole/swoole/timer/info.xml b/reference/swoole/swoole/timer/info.xml
new file mode 100644
index 000000000000..35e785a1299c
--- /dev/null
+++ b/reference/swoole/swoole/timer/info.xml
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-timer.info" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>Swoole\Timer::info</refname>
+ <refpurpose>Get information about a timer.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <modifier>public</modifier> <modifier>static</modifier> <type
class="union"><type>array</type><type>null</type></type><methodname>Swoole\Timer::info</methodname>
+
<methodparam><type>int</type><parameter>timer_id</parameter></methodparam>
+ </methodsynopsis>
+ <simpara>
+ Get information about a timer. As of Swoole 4.4.0.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <variablelist>
+ <varlistentry>
+ <term><parameter>timer_id</parameter></term>
+ <listitem>
+ <simpara>
+ The timer ID returned by <methodname>Swoole\Timer::tick</methodname> or
+ <methodname>Swoole\Timer::after</methodname>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ Returns an array describing the timer, or &null; if no timer with this ID
+ exists in the current process. The array contains the following keys:
+ </simpara>
+ <variablelist>
+ <varlistentry>
+ <term><literal>exec_msec</literal></term>
+ <listitem>
+ <simpara>
+ The time of the next execution, in milliseconds, counted from the moment
+ the timer subsystem was started. It is not a duration.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>exec_count</literal></term>
+ <listitem>
+ <simpara>
+ The number of times the callback has been executed.
+ Available as of Swoole 4.8.0.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>interval</literal></term>
+ <listitem>
+ <simpara>
+ The interval of the timer, in milliseconds.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>round</literal></term>
+ <listitem>
+ <simpara>
+ The number of the timer loop round in which the timer was created.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>removed</literal></term>
+ <listitem>
+ <simpara>
+ Whether the timer has been removed.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>Swoole\Timer::info</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timer_id = Swoole\Timer::tick(1000, function () {});
+var_dump(Swoole\Timer::info($timer_id));
+Swoole\Timer::clear($timer_id);
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+array(5) {
+ ["exec_msec"]=>
+ int(1000)
+ ["exec_count"]=>
+ int(0)
+ ["interval"]=>
+ int(1000)
+ ["round"]=>
+ int(0)
+ ["removed"]=>
+ bool(false)
+}
+]]>
+ </screen>
+ </example>
+ </refsect1>
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/swoole/swoole/timer/list.xml b/reference/swoole/swoole/timer/list.xml
new file mode 100644
index 000000000000..fce061baf553
--- /dev/null
+++ b/reference/swoole/swoole/timer/list.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-timer.list" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>Swoole\Timer::list</refname>
+ <refpurpose>Get an iterator over the timers of the current process</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <modifier>public</modifier> <modifier>static</modifier>
<type>Swoole\Timer\Iterator</type><methodname>Swoole\Timer::list</methodname>
+ <void/>
+ </methodsynopsis>
+ <simpara>
+ Returns an iterator over the IDs of the timers created from PHP in the
+ current process. Timers created internally by Swoole are not listed.
+ As of Swoole 4.4.0.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ Returns a <classname>Swoole\Timer\Iterator</classname> object, which
+ extends <classname>ArrayIterator</classname> and yields the timer IDs as
+ <type>int</type> values. The iterator is a snapshot taken when the method is
+ called; it is empty when no timer exists.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>Swoole\Timer::list</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+Swoole\Timer::tick(1000, function () {});
+Swoole\Timer::after(5000, function () {});
+
+foreach (Swoole\Timer::list() as $timer_id) {
+ echo $timer_id, "\n";
+ Swoole\Timer::clear($timer_id);
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+1
+2
+]]>
+ </screen>
+ </example>
+ </refsect1>
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/swoole/swoole/timer/set.xml b/reference/swoole/swoole/timer/set.xml
new file mode 100644
index 000000000000..78cca7975243
--- /dev/null
+++ b/reference/swoole/swoole/timer/set.xml
@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-timer.set" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>Swoole\Timer::set</refname>
+ <refpurpose>Set timer-related parameters</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <modifier>public</modifier> <modifier>static</modifier>
<type>void</type><methodname>Swoole\Timer::set</methodname>
+
<methodparam><type>array</type><parameter>settings</parameter></methodparam>
+ </methodsynopsis>
+ <simpara>
+ Sets the options used by the timers of the current process.
+ </simpara>
+
+ <warning>
+ <simpara>
+ This method was deprecated in Swoole 4.6.0 and removed in Swoole 6.0.0.
+ Use <function>swoole_async_set</function> instead.
+ </simpara>
+ </warning>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <variablelist>
+ <varlistentry>
+ <term><parameter>settings</parameter></term>
+ <listitem>
+ <simpara>
+ An associative array of options. Only <literal>enable_coroutine</literal>
+ is recognised: when set to &false;, the timer callbacks are executed
+ directly instead of inside a newly created coroutine.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ &return.void;
+ </simpara>
+ </refsect1>
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/swoole/swoole/timer/stats.xml b/reference/swoole/swoole/timer/stats.xml
new file mode 100644
index 000000000000..e7424e481e55
--- /dev/null
+++ b/reference/swoole/swoole/timer/stats.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="swoole-timer.stats" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>Swoole\Timer::stats</refname>
+ <refpurpose>Get timer statistics.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <modifier>public</modifier> <modifier>static</modifier>
<type>array</type><methodname>Swoole\Timer::stats</methodname>
+ <void/>
+ </methodsynopsis>
+ <simpara>
+ Get timer statistics. As of Swoole 4.4.0.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ Returns an array with the following keys:
+ </simpara>
+ <variablelist>
+ <varlistentry>
+ <term><literal>initialized</literal></term>
+ <listitem>
+ <simpara>
+ Whether the timer subsystem has been started. It is &false; until the
+ first timer is created.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>num</literal></term>
+ <listitem>
+ <simpara>
+ The number of timers currently registered in the process.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>round</literal></term>
+ <listitem>
+ <simpara>
+ The current round of the timer loop.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>Swoole\Timer::stats</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timer_id = Swoole\Timer::tick(1000, function () {});
+var_dump(Swoole\Timer::stats());
+Swoole\Timer::clear($timer_id);
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+array(3) {
+ ["initialized"]=>
+ bool(true)
+ ["num"]=>
+ int(1)
+ ["round"]=>
+ int(0)
+}
+]]>
+ </screen>
+ </example>
+ </refsect1>
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/swoole/swoole/timer/tick.xml b/reference/swoole/swoole/timer/tick.xml
index 12da8aa17a7b..5c8a20bca9d1 100644
--- a/reference/swoole/swoole/timer/tick.xml
+++ b/reference/swoole/swoole/timer/tick.xml
@@ -4,48 +4,56 @@
<refentry xml:id="swoole-timer.tick" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Timer::tick</refname>
- <refpurpose>Repeats a given function at every given time-interval.</refpurpose>
+ <refpurpose>Set a repeating interval timer</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <modifier>public</modifier> <modifier>static</modifier>
<type>void</type><methodname>Swoole\Timer::tick</methodname>
-
<methodparam><type>int</type><parameter>interval_ms</parameter></methodparam>
+ <modifier>public</modifier> <modifier>static</modifier> <type
class="union"><type>int</type><type>false</type></type><methodname>Swoole\Timer::tick</methodname>
+
<methodparam><type>int</type><parameter>ms</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
- <methodparam
choice="opt"><type>string</type><parameter>param</parameter></methodparam>
+ <methodparam
rep="repeat"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
- <para>
-
- </para>
-
+ <simpara>
+ Sets a timer that triggers every <parameter>ms</parameter> milliseconds.
+ Unlike a timer created with <methodname>Swoole\Timer::after</methodname>,
+ it keeps triggering until it is removed with
+ <methodname>Swoole\Timer::clear</methodname>.
+ </simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
- <term><parameter>interval_ms</parameter></term>
+ <term><parameter>ms</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ The interval in milliseconds. Must be greater than or equal to
+ <literal>1</literal>; a lower value emits an
<constant>E_WARNING</constant>
+ and the call fails.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ The function to execute on every tick. It is called as
+ <literal>callback(int $timer_id, mixed ...$params)</literal>: the ID of
+ the timer is passed as the first argument, followed by the values given
+ in <parameter>params</parameter>.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>param</parameter></term>
+ <term><parameter>params</parameter></term>
<listitem>
- <para>
-
- </para>
+ <simpara>
+ Additional values passed to <parameter>callback</parameter> after the
+ timer ID.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -53,12 +61,41 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
-
- </para>
+ <simpara>
+ Returns the timer ID, which can be passed to
+ <methodname>Swoole\Timer::clear</methodname>. Returns &false; if the timer
+ could not be created, in particular when <parameter>ms</parameter> is less
+ than <literal>1</literal>.
+ </simpara>
</refsect1>
-
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><function>Swoole\Timer::tick</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$ticks = 0;
+Swoole\Timer::tick(1000, function (int $timer_id, string $label) use (&$ticks) {
+ echo "tick #", ++$ticks, " ($label)\n";
+ if ($ticks === 3) {
+ Swoole\Timer::clear($timer_id);
+ }
+}, "job");
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+tick #1 (job)
+tick #2 (job)
+tick #3 (job)
+]]>
+ </screen>
+ </example>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file