[doc-en] master: optimize swoole timer docs (#4773)

From: 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

« previous php.doc.cvs (#23699) next »