Skip to content

[Sync-En] swoole: document the Timer class and its remaining methods #1245

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

Merged
julionc merged 2 commits into from
Sep 3, 2026
Merged

[Sync-En] swoole: document the Timer class and its remaining methods #1245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a1903aa
[Sync-En] swoole: document the Timer class and its remaining methods
lacatoire Sep 3, 2026
c249916
swoole: use the required default wording and keep the modal of the En…
lacatoire Sep 3, 2026
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
70 changes: 68 additions & 2 deletions reference/swoole/swoole.timer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4d17b7b4947e7819ff5036715dd706be87ae4def Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 6e77169fdc9c087749f357bef877607ccc05f442 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes Maintainer: Marqitos -->
<reference xml:id="class.swoole-timer" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>La clase Swoole\Timer</title>
Expand All @@ -10,9 +10,75 @@
<!-- {{{ Swoole\Timer intro -->
<section xml:id="swoole-timer.intro">
&reftitle.intro;
<simpara>
Temporizador con precisión de milisegundos. La implementación subyacente se
basa en epoll_wait y setitimer, con una estructura de datos de montículo
mínimo que permite añadir un gran número de temporizadores.
</simpara>
<simpara>
En los procesos con E/S síncrona, como los procesos Manager y TaskWorker, se
implementa mediante setitimer y señales.
</simpara>
<simpara>
En los procesos con E/S asíncrona, se implementa mediante el tiempo de
espera de epoll_wait/kevent/poll/select.
</simpara>
<para>

El sistema subyacente no admite temporizadores con un retardo de
<literal>0</literal>; los valores inferiores a <literal>1</literal>
milisegundo emiten un <constant>E_WARNING</constant> y la llamada falla.
Esto difiere de lenguajes como Node.js.
<methodname linkend="swoole-event.defer">Swoole\Event::defer</methodname>
puede utilizarse para obtener una funcionalidad similar.
<programlisting role="php">
<![CDATA[
<?php
Swoole\Event::defer(function () {
echo "hola\n";
});
?>
]]>
</programlisting>
</para>
<simpara>
Corrección del temporizador: el tiempo de ejecución de la función de
retrollamada no afecta al instante de la siguiente ejecución. Por ejemplo,
para un temporizador tick de 10 ms creado en 0,002 s, la primera
retrollamada se ejecuta en 0,012 s; si la función de retrollamada tarda
5 ms, el siguiente disparo se produce igualmente en 0,022 s, y no en
0,027 s.
</simpara>
<simpara>
En cambio, si la función de retrollamada tarda demasiado, hasta cubrir el
instante de la siguiente ejecución, el sistema subyacente corrige el tiempo:
descarta los disparos vencidos y vuelve a llamar a la función en el
siguiente instante disponible. Por ejemplo, si la retrollamada ejecutada en
0,012 s tarda 15 ms, lo que retrasa el temporizador previsto para 0,022 s,
la retrollamada se dispara de nuevo en 0,032 s.
</simpara>
<simpara>
De forma predeterminada, cuando un temporizador se dispara se crea
automáticamente una corrutina para ejecutar la función de retrollamada.
Este comportamiento puede desactivarse con
<function>swoole_async_set</function>.
</simpara>
<warning>
<simpara>
Un temporizador solo funciona en el espacio del proceso actual.
</simpara>
</warning>
<warning>
<simpara>
Los temporizadores son puramente asíncronos e incompatibles con las
funciones de E/S síncrona.
</simpara>
</warning>
<warning>
<simpara>
La ejecución de un temporizador puede presentar ligeras desviaciones de
tiempo.
</simpara>
</warning>
</section>
<!-- }}} -->

Expand Down
76 changes: 58 additions & 18 deletions reference/swoole/swoole/timer/after.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,54 +1,94 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 322606e4f1742a6f959e952c63fb1f8bcd6d6ba0 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 6e77169fdc9c087749f357bef877607ccc05f442 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<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>Dispara una retrollamada después de un período de tiempo.</refpurpose>
<refpurpose>Ejecuta una función después de un tiempo determinado</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>
Dispara una retrollamada después de un período de tiempo.
</para>

<simpara>
Crea un temporizador de un solo disparo, que se destruye una vez ejecutada
su retrollamada. A diferencia de <function>sleep</function>, no bloquea el
proceso actual.
</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>
El retardo en milisegundos. Debe ser mayor o igual que
<literal>1</literal>; un valor inferior emite un
<constant>E_WARNING</constant> y la llamada falla.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>

</para>
<simpara>
La función a ejecutar una vez transcurrido el retardo. Se llama como
<literal>callback(mixed ...$params)</literal>. A diferencia de
<methodname>Swoole\Timer::tick</methodname>, el identificador del
temporizador no se pasa a la retrollamada.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<simpara>
Valores adicionales que se pasan a <parameter>callback</parameter>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

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

</para>
<simpara>
Devuelve el identificador del temporizador, que puede pasarse a
<methodname>Swoole\Timer::clear</methodname> para cancelarlo antes de que se
dispare. Devuelve &false; si el temporizador no ha podido crearse, en
particular cuando <parameter>ms</parameter> es menor que
<literal>1</literal>.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Ejemplo de <function>Swoole\Timer::after</function></title>
<programlisting role="php">
<![CDATA[
<?php
Swoole\Timer::after(1000, function (string $name) {
echo "Hola, $name\n";
}, "Swoole");
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Hola, Swoole
]]>
</screen>
</example>
</refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Expand Down
54 changes: 41 additions & 13 deletions reference/swoole/swoole/timer/clear.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,23 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 6e77169fdc9c087749f357bef877607ccc05f442 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<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>Elimina un temporizador por ID de temporizador.</refpurpose>
<refpurpose>Elimina un temporizador por su identificador</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>
Elimina un temporizador por ID de temporizador.
</para>

<simpara>
Elimina el temporizador con el identificador indicado. Solo pueden
eliminarse los temporizadores creados por el proceso actual; los
temporizadores que pertenecen a otros procesos no son visibles aquí.
</simpara>
</refsect1>

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

</para>
<simpara>
El identificador del temporizador devuelto por
<methodname>Swoole\Timer::tick</methodname> o
<methodname>Swoole\Timer::after</methodname>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

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

</para>
<simpara>
&return.success;
Se devuelve &false; cuando no existe ningún temporizador con este
identificador en el proceso actual, o cuando el identificador corresponde a
un temporizador interno.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Ejemplo de <function>Swoole\Timer::clear</function></title>
<programlisting role="php">
<![CDATA[
<?php
$timer_id = Swoole\Timer::after(1000, function () {
echo "nunca se imprime\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
Expand Down
51 changes: 51 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,51 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 6e77169fdc9c087749f357bef877607ccc05f442 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<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>Elimina todos los temporizadores del proceso actual.</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>
Elimina todos los temporizadores del proceso actual. A partir de Swoole 4.4.0.
</simpara>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
&return.success;
Se devuelve &false; cuando todavía no se ha creado ningún temporizador en
este proceso. Solo se eliminan los temporizadores creados desde PHP; los
temporizadores internos se mantienen.
</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
-->
27 changes: 16 additions & 11 deletions reference/swoole/swoole/timer/exists.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 86e6094e86b84a51d00ab217ac50ce8dde33d82a Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 6e77169fdc9c087749f357bef877607ccc05f442 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="swoole-timer.exists" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Swoole\Timer::exists</refname>
<refpurpose>Verifica si un temporizador existe.</refpurpose>
<refpurpose>Comprueba si un temporizador existe</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -13,9 +13,10 @@
<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>
Verifica si un temporizador existe.
</para>
<simpara>
Comprueba si existe en el proceso actual un temporizador con el
identificador indicado.
</simpara>

</refsect1>

Expand All @@ -25,21 +26,25 @@
<varlistentry>
<term><parameter>timer_id</parameter></term>
<listitem>
<para>

</para>
<simpara>
El identificador del temporizador devuelto por
<methodname>Swoole\Timer::tick</methodname> o
<methodname>Swoole\Timer::after</methodname>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

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

</para>
<simpara>
Devuelve &true; si existe un temporizador con este identificador en el
proceso actual, y &false; en caso contrario.
</simpara>
</refsect1>


</refentry>

<!-- Keep this comment at the end of the file
Expand Down
Loading