Skip to content

optimize swoole timer docs #4773

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

optimize swoole timer docs #4773

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions reference/swoole/swoole.timer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,58 @@
<section xml:id="swoole-timer.intro">
&reftitle.intro;
<para>
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.
</para>
<para>
In synchronous IO processes, it's implemented using setitimer and signals, such as in Manager and TaskWorker processes.
</para>
<para>
In asynchronous IO processes, it's implemented using the timeout of epoll_wait/kevent/poll/select.
</para>
<para>
The underlying system does not support timers with a time parameter of 0. This is different from languages like Node.js.
In Swoole, you can use Swoole\Event::defer to achieve similar functionality.
<programlisting role="php">
<![CDATA[
<?php
Swoole\Event::defer(function () {
echo "hello\n";
});
?>
]]>
</programlisting>
</para>
<para>
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.

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.
</para>
<para>
By default, when a timer is triggered, a coroutine is automatically created to execute the callback function.
</para>
<warning>
<simpara>
Timer only works within the current process space.
</simpara>
</warning>
<warning>
<simpara>
Timer is purely asynchronous and incompatible with synchronous IO functions.
</simpara>
</warning>
<warning>
<simpara>
Timer execution may experience minor timing deviations.
</simpara>
</warning>
</section>
<!-- }}} -->

Expand Down
50 changes: 38 additions & 12 deletions reference/swoole/swoole/timer/after.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,38 +4,47 @@
<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 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>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
<modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>Swoole\Timer::after</methodname>
<methodparam><type>int</type><parameter>msec</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback_function</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Trigger a callback function after a period of time.
Execute a function after a specified time. The Swoole\Timer::after function is a one-time timer that will be
destroyed once executed.
</para>

</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>after_time_ms</parameter></term>
<term><parameter>msec</parameter></term>
<listitem>
<para>

Specified time in milliseconds (e.g. 1000 means 1 second).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callback</parameter></term>
<term><parameter>callback_function</parameter></term>
<listitem>
<para>

The callback function to be executed when timer expires.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
Additional parameters to pass to the callback function.
</para>
</listitem>
</varlistentry>
Expand All @@ -45,11 +54,28 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

Returns timer ID which can be used to clear the timer.
</para>
</refsect1>


<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>Swoole\Timer::after</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$str = "Swoole";
Swoole\Timer::after(1000, function() use ($str) {
echo "Hello, $str\n";
});
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Expand Down
33 changes: 16 additions & 17 deletions reference/swoole/swoole/timer/clear.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,43 +4,42 @@
<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>Clear 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.
Use timer ID to delete a timer. Cannot be used to clear timers from other processes.
</para>

</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>timer_id</parameter></term>
<listitem>
<para>

</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<variablelist>
<varlistentry>
<term><parameter>timer_id</parameter></term>
<listitem>
<para>
The timer ID returned by Timer::tick or Timer::after.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

&return.success;
</para>
</refsect1>


</refentry>

<!-- Keep this comment at the end of the file
Expand Down
48 changes: 48 additions & 0 deletions reference/swoole/swoole/timer/clearAll.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<?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 current worker 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>
<para>
Clear all timers in current worker process. Available since Swoole version >= v4.4.0.
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</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
-->
26 changes: 16 additions & 10 deletions reference/swoole/swoole/timer/exists.xml → reference/swoole/swoole/timer/info.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="swoole-timer.exists" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refentry xml:id="swoole-timer.info" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Timer::exists</refname>
<refpurpose>Check if a timer is existed.</refpurpose>
<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>bool</type><methodname>Swoole\Timer::exists</methodname>
<modifier>public</modifier> <modifier>static</modifier> <type>array</type><methodname>Swoole\Timer::info</methodname>
<methodparam><type>int</type><parameter>timer_id</parameter></methodparam>
</methodsynopsis>
<para>
Check if a timer is existed.
Get information about a timer. Available since Swoole version >= v4.4.0.
</para>

</refsect1>

<refsect1 role="parameters">
Expand All @@ -26,7 +25,7 @@
<term><parameter>timer_id</parameter></term>
<listitem>
<para>

The timer ID
</para>
</listitem>
</varlistentry>
Expand All @@ -36,11 +35,18 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>

Returns an array with timer information:
<![CDATA[
array(5) {
["exec_msec"]=> int(6000)
["exec_count"]=> int(5)
["interval"]=> int(1000)
["round"]=> int(0)
["removed"]=> bool(false)
}
]]>
</para>
</refsect1>


</refentry>

<!-- Keep this comment at the end of the file
Expand Down
66 changes: 66 additions & 0 deletions reference/swoole/swoole/timer/list.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
<?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 iterator for all timers in current worker 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>
<para>
Returns timer iterator which can be used to traverse all timer IDs in current worker process.
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns Swoole\Timer\Iterator object.
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>Swoole\Timer::list</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
foreach (Swoole\Timer::list() as $timer_id) {
var_dump(Swoole\Timer::info($timer_id));
}
?>
]]>
</programlisting>
</example>
</para>
</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
-->
Loading