From a1903aad2a549d2c18e1f7753e8f3a75b0857e64 Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Date: Thu, 3 Sep 2026 13:52:06 +0200 Subject: [PATCH 1/2] [Sync-En] swoole: document the Timer class and its remaining methods --- reference/swoole/swoole.timer.xml | 69 +++++++++- reference/swoole/swoole/timer/after.xml | 76 ++++++++--- reference/swoole/swoole/timer/clear.xml | 54 ++++++-- reference/swoole/swoole/timer/clearAll.xml | 51 ++++++++ reference/swoole/swoole/timer/exists.xml | 27 ++-- reference/swoole/swoole/timer/info.xml | 145 +++++++++++++++++++++ reference/swoole/swoole/timer/list.xml | 81 ++++++++++++ reference/swoole/swoole/timer/set.xml | 72 ++++++++++ reference/swoole/swoole/timer/stats.xml | 104 +++++++++++++++ reference/swoole/swoole/timer/tick.xml | 84 ++++++++---- 10 files changed, 696 insertions(+), 67 deletions(-) create mode 100644 reference/swoole/swoole/timer/clearAll.xml create mode 100644 reference/swoole/swoole/timer/info.xml create mode 100644 reference/swoole/swoole/timer/list.xml create mode 100644 reference/swoole/swoole/timer/set.xml create mode 100644 reference/swoole/swoole/timer/stats.xml diff --git a/reference/swoole/swoole.timer.xml b/reference/swoole/swoole.timer.xml index 8e14668a17..5bf949c4f3 100644 --- a/reference/swoole/swoole.timer.xml +++ b/reference/swoole/swoole.timer.xml @@ -1,5 +1,5 @@ - + La clase Swoole\Timer @@ -10,9 +10,74 @@
&reftitle.intro; + + 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. + + + En los procesos con E/S síncrona, como los procesos Manager y TaskWorker, se + implementa mediante setitimer y señales. + + + En los procesos con E/S asíncrona, se implementa mediante el tiempo de + espera de epoll_wait/kevent/poll/select. + - + El sistema subyacente no admite temporizadores con un retardo de + 0; los valores inferiores a 1 + milisegundo emiten un E_WARNING y la llamada falla. + Esto difiere de lenguajes como Node.js. + Swoole\Event::defer + puede utilizarse para obtener una funcionalidad similar. + + +]]> + + + 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. + + + 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. + + + Por omisión, cuando un temporizador se dispara se crea automáticamente una + corrutina para ejecutar la función de retrollamada. Este comportamiento se + desactiva con swoole_async_set. + + + + Un temporizador solo funciona en el espacio del proceso actual. + + + + + Los temporizadores son puramente asíncronos e incompatibles con las + funciones de E/S síncrona. + + + + + La ejecución de un temporizador puede presentar ligeras desviaciones de + tiempo. + +
diff --git a/reference/swoole/swoole/timer/after.xml b/reference/swoole/swoole/timer/after.xml index 3d77cdc35c..63dd7545fc 100644 --- a/reference/swoole/swoole/timer/after.xml +++ b/reference/swoole/swoole/timer/after.xml @@ -1,42 +1,57 @@ - + Swoole\Timer::after - Dispara una retrollamada después de un período de tiempo. + Ejecuta una función después de un tiempo determinado &reftitle.description; - public static voidSwoole\Timer::after - intafter_time_ms + public static intfalseSwoole\Timer::after + intms callablecallback + mixedparams - - Dispara una retrollamada después de un período de tiempo. - - + + Crea un temporizador de un solo disparo, que se destruye una vez ejecutada + su retrollamada. A diferencia de sleep, no bloquea el + proceso actual. + &reftitle.parameters; - after_time_ms + ms - - - + + El retardo en milisegundos. Debe ser mayor o igual que + 1; un valor inferior emite un + E_WARNING y la llamada falla. + callback - - - + + La función a ejecutar una vez transcurrido el retardo. Se llama como + callback(mixed ...$params). A diferencia de + Swoole\Timer::tick, el identificador del + temporizador no se pasa a la retrollamada. + + + + + params + + + Valores adicionales que se pasan a callback. + @@ -44,11 +59,36 @@ &reftitle.returnvalues; - - - + + Devuelve el identificador del temporizador, que puede pasarse a + Swoole\Timer::clear para cancelarlo antes de que se + dispare. Devuelve &false; si el temporizador no ha podido crearse, en + particular cuando ms es menor que + 1. + + + &reftitle.examples; + + Ejemplo de <function>Swoole\Timer::after</function> + + +]]> + + &example.outputs; + + + + + + Swoole\Timer::clear - Elimina un temporizador por ID de temporizador. + Elimina un temporizador por su identificador &reftitle.description; - public static voidSwoole\Timer::clear + public static boolSwoole\Timer::clear inttimer_id - - Elimina un temporizador por ID de temporizador. - - + + 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í. + @@ -25,9 +26,11 @@ timer_id - - - + + El identificador del temporizador devuelto por + Swoole\Timer::tick o + Swoole\Timer::after. + @@ -35,11 +38,36 @@ &reftitle.returnvalues; - - - + + &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. + + + &reftitle.examples; + + Ejemplo de <function>Swoole\Timer::clear</function> + + +]]> + + &example.outputs; + + + + + + + + + Swoole\Timer::clearAll + Elimina todos los temporizadores del proceso actual. + + + + &reftitle.description; + + public static boolSwoole\Timer::clearAll + + + + Elimina todos los temporizadores del proceso actual. A partir de Swoole 4.4.0. + + + + + &reftitle.returnvalues; + + &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. + + + + + diff --git a/reference/swoole/swoole/timer/exists.xml b/reference/swoole/swoole/timer/exists.xml index 1f3000d26b..758e533cb3 100644 --- a/reference/swoole/swoole/timer/exists.xml +++ b/reference/swoole/swoole/timer/exists.xml @@ -1,10 +1,10 @@ - + Swoole\Timer::exists - Verifica si un temporizador existe. + Comprueba si un temporizador existe @@ -13,9 +13,10 @@ public static boolSwoole\Timer::exists inttimer_id - - Verifica si un temporizador existe. - + + Comprueba si existe en el proceso actual un temporizador con el + identificador indicado. + @@ -25,9 +26,11 @@ timer_id - - - + + El identificador del temporizador devuelto por + Swoole\Timer::tick o + Swoole\Timer::after. + @@ -35,11 +38,13 @@ &reftitle.returnvalues; - - - + + Devuelve &true; si existe un temporizador con este identificador en el + proceso actual, y &false; en caso contrario. + + + + + + Swoole\Timer::info + Obtiene información sobre un temporizador. + + + + &reftitle.description; + + public static arraynullSwoole\Timer::info + inttimer_id + + + Obtiene información sobre un temporizador. A partir de Swoole 4.4.0. + + + + + &reftitle.parameters; + + + timer_id + + + El identificador del temporizador devuelto por + Swoole\Timer::tick o + Swoole\Timer::after. + + + + + + + + &reftitle.returnvalues; + + Devuelve un array que describe el temporizador, o &null; si no existe + ningún temporizador con este identificador en el proceso actual. El array + contiene las siguientes claves: + + + + exec_msec + + + El instante de la siguiente ejecución, en milisegundos, contado desde el + momento en que se inició el subsistema de temporizadores. No es una + duración. + + + + + exec_count + + + El número de veces que se ha ejecutado la retrollamada. + Disponible a partir de Swoole 4.8.0. + + + + + interval + + + El intervalo del temporizador, en milisegundos. + + + + + round + + + El número de la vuelta del bucle de temporizadores en la que se creó el + temporizador. + + + + + removed + + + Indica si el temporizador ha sido eliminado. + + + + + + + + &reftitle.examples; + + Ejemplo de <function>Swoole\Timer::info</function> + + +]]> + + &example.outputs.similar; + + + int(1000) + ["exec_count"]=> + int(0) + ["interval"]=> + int(1000) + ["round"]=> + int(0) + ["removed"]=> + bool(false) +} +]]> + + + + + + diff --git a/reference/swoole/swoole/timer/list.xml b/reference/swoole/swoole/timer/list.xml new file mode 100644 index 0000000000..9c3a2461b3 --- /dev/null +++ b/reference/swoole/swoole/timer/list.xml @@ -0,0 +1,81 @@ + + + + + + Swoole\Timer::list + Obtiene un iterador sobre los temporizadores del proceso actual + + + + &reftitle.description; + + public static Swoole\Timer\IteratorSwoole\Timer::list + + + + Devuelve un iterador sobre los identificadores de los temporizadores creados + desde PHP en el proceso actual. Los temporizadores creados internamente por + Swoole no se enumeran. A partir de Swoole 4.4.0. + + + + + &reftitle.returnvalues; + + Devuelve un objeto Swoole\Timer\Iterator, que extiende + ArrayIterator y proporciona los identificadores de + los temporizadores como valores int. El iterador es una + instantánea tomada en el momento de la llamada; está vacío cuando no existe + ningún temporizador. + + + + + &reftitle.examples; + + Ejemplo de <function>Swoole\Timer::list</function> + + +]]> + + &example.outputs.similar; + + + + + + + + diff --git a/reference/swoole/swoole/timer/set.xml b/reference/swoole/swoole/timer/set.xml new file mode 100644 index 0000000000..5b34729ac2 --- /dev/null +++ b/reference/swoole/swoole/timer/set.xml @@ -0,0 +1,72 @@ + + + + + + Swoole\Timer::set + Define los parámetros relacionados con los temporizadores + + + + &reftitle.description; + + public static voidSwoole\Timer::set + arraysettings + + + Define las opciones utilizadas por los temporizadores del proceso actual. + + + + + Este método quedó obsoleto en Swoole 4.6.0 y se eliminó en Swoole 6.0.0. + Utilice swoole_async_set en su lugar. + + + + + + &reftitle.parameters; + + + settings + + + Un array asociativo de opciones. Solo se reconoce + enable_coroutine: cuando vale &false;, las + retrollamadas de los temporizadores se ejecutan directamente y no dentro + de una corrutina creada al efecto. + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/swoole/swoole/timer/stats.xml b/reference/swoole/swoole/timer/stats.xml new file mode 100644 index 0000000000..cba8c59ba9 --- /dev/null +++ b/reference/swoole/swoole/timer/stats.xml @@ -0,0 +1,104 @@ + + + + + + Swoole\Timer::stats + Obtiene estadísticas de los temporizadores. + + + + &reftitle.description; + + public static arraySwoole\Timer::stats + + + + Obtiene estadísticas de los temporizadores. A partir de Swoole 4.4.0. + + + + + &reftitle.returnvalues; + + Devuelve un array con las siguientes claves: + + + + initialized + + + Indica si el subsistema de temporizadores ha sido iniciado. Vale &false; + hasta que se crea el primer temporizador. + + + + + num + + + El número de temporizadores registrados actualmente en el proceso. + + + + + round + + + La vuelta actual del bucle de temporizadores. + + + + + + + + &reftitle.examples; + + Ejemplo de <function>Swoole\Timer::stats</function> + + +]]> + + &example.outputs.similar; + + + bool(true) + ["num"]=> + int(1) + ["round"]=> + int(0) +} +]]> + + + + + + diff --git a/reference/swoole/swoole/timer/tick.xml b/reference/swoole/swoole/timer/tick.xml index 8199ab97e4..4bb5618563 100644 --- a/reference/swoole/swoole/timer/tick.xml +++ b/reference/swoole/swoole/timer/tick.xml @@ -1,51 +1,59 @@ - + Swoole\Timer::tick - Repite una función dada en cada intervalo de tiempo dado. + Define un temporizador de intervalo repetitivo &reftitle.description; - public static voidSwoole\Timer::tick - intinterval_ms + public static intfalseSwoole\Timer::tick + intms callablecallback - stringparam + mixedparams - - - - + + Define un temporizador que se dispara cada ms + milisegundos. A diferencia de un temporizador creado con + Swoole\Timer::after, sigue disparándose hasta que + se elimina con Swoole\Timer::clear. + &reftitle.parameters; - interval_ms + ms - - - + + El intervalo en milisegundos. Debe ser mayor o igual que + 1; un valor inferior emite un + E_WARNING y la llamada falla. + callback - - - + + La función a ejecutar en cada disparo. Se llama como + callback(int $timer_id, mixed ...$params): el + identificador del temporizador se pasa como primer argumento, seguido de + los valores indicados en params. + - param + params - - - + + Valores adicionales que se pasan a callback + después del identificador del temporizador. + @@ -53,11 +61,41 @@ &reftitle.returnvalues; - - - + + Devuelve el identificador del temporizador, que puede pasarse a + Swoole\Timer::clear. Devuelve &false; si el + temporizador no ha podido crearse, en particular cuando + ms es menor que 1. + + + &reftitle.examples; + + Ejemplo de <function>Swoole\Timer::tick</function> + + +]]> + + &example.outputs; + + + + +