From a3d4bdd5f64736c8ed30e2d54cc2713456745fd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sun, 25 Mar 2018 19:23:00 +0200 Subject: [PATCH 1/2] Documentation for millisecond timer accuracy --- README.md | 24 ++++++++++++++++++++---- src/LoopInterface.php | 24 ++++++++++++++++++++---- 2 files changed, 40 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5ee4d8e5..beb5e6cd 100644 --- a/README.md +++ b/README.md @@ -281,8 +281,16 @@ function hello($name, LoopInterface $loop) hello('Tester', $loop); ``` -The execution order of timers scheduled to execute at the same time is -not guaranteed. +This interface does not enforce any particular timer resolution, so +special care may have to be taken if you rely on very high precision with +millisecond accuracy or below. Event loop implementations SHOULD work on +a best effort basis and SHOULD provide at least millisecond accuracy +unless otherwise noted. Many existing event loop implementations are +known to provide microsecond accuracy, but it's generally not recommended +to rely on this high precision. + +Similarly, the execution order of timers scheduled to execute at the +same time (within its possible accuracy) is not guaranteed. This interface suggests that event loop implementations SHOULD use a monotic time source if available. Given that a monotonic time source is @@ -346,8 +354,16 @@ function hello($name, LoopInterface $loop) hello('Tester', $loop); ``` -The execution order of timers scheduled to execute at the same time is -not guaranteed. +This interface does not enforce any particular timer resolution, so +special care may have to be taken if you rely on very high precision with +millisecond accuracy or below. Event loop implementations SHOULD work on +a best effort basis and SHOULD provide at least millisecond accuracy +unless otherwise noted. Many existing event loop implementations are +known to provide microsecond accuracy, but it's generally not recommended +to rely on this high precision. + +Similarly, the execution order of timers scheduled to execute at the +same time (within its possible accuracy) is not guaranteed. #### cancelTimer() diff --git a/src/LoopInterface.php b/src/LoopInterface.php index ebf58755..9401922f 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -168,8 +168,16 @@ public function removeWriteStream($stream); * hello('Tester', $loop); * ``` * - * The execution order of timers scheduled to execute at the same time is - * not guaranteed. + * This interface does not enforce any particular timer resolution, so + * special care may have to be taken if you rely on very high precision with + * millisecond accuracy or below. Event loop implementations SHOULD work on + * a best effort basis and SHOULD provide at least millisecond accuracy + * unless otherwise noted. Many existing event loop implementations are + * known to provide microsecond accuracy, but it's generally not recommended + * to rely on this high precision. + * + * Similarly, the execution order of timers scheduled to execute at the + * same time (within its possible accuracy) is not guaranteed. * * @param int|float $interval The number of seconds to wait before execution. * @param callable $callback The callback to invoke. @@ -227,8 +235,16 @@ public function addTimer($interval, $callback); * hello('Tester', $loop); * ``` * - * The execution order of timers scheduled to execute at the same time is - * not guaranteed. + * This interface does not enforce any particular timer resolution, so + * special care may have to be taken if you rely on very high precision with + * millisecond accuracy or below. Event loop implementations SHOULD work on + * a best effort basis and SHOULD provide at least millisecond accuracy + * unless otherwise noted. Many existing event loop implementations are + * known to provide microsecond accuracy, but it's generally not recommended + * to rely on this high precision. + * + * Similarly, the execution order of timers scheduled to execute at the + * same time (within its possible accuracy) is not guaranteed. * * This interface suggests that event loop implementations SHOULD use a * monotic time source if available. Given that a monotonic time source is From f432daa1c8795ae4a257eac69d9c29cd4f850e49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sun, 25 Mar 2018 22:02:17 +0200 Subject: [PATCH 2/2] Documentation for timer drift for periodic timers --- README.md | 18 +++++++++++++++++- src/LoopInterface.php | 18 +++++++++++++++++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index beb5e6cd..6912e021 100644 --- a/README.md +++ b/README.md @@ -293,7 +293,7 @@ Similarly, the execution order of timers scheduled to execute at the same time (within its possible accuracy) is not guaranteed. This interface suggests that event loop implementations SHOULD use a -monotic time source if available. Given that a monotonic time source is +monotonic time source if available. Given that a monotonic time source is not available on PHP by default, event loop implementations MAY fall back to using wall-clock time. While this does not affect many common use cases, this is an important @@ -365,6 +365,22 @@ to rely on this high precision. Similarly, the execution order of timers scheduled to execute at the same time (within its possible accuracy) is not guaranteed. +This interface suggests that event loop implementations SHOULD use a +monotonic time source if available. Given that a monotonic time source is +not available on PHP by default, event loop implementations MAY fall back +to using wall-clock time. +While this does not affect many common use cases, this is an important +distinction for programs that rely on a high time precision or on systems +that are subject to discontinuous time adjustments (time jumps). +This means that if you schedule a timer to trigger in 30s and then adjust +your system time forward by 20s, the timer SHOULD still trigger in 30s. +See also [event loop implementations](#loop-implementations) for more details. + +Additionally, periodic timers may be subject to timer drift due to +re-scheduling after each invocation. As such, it's generally not +recommended to rely on this for high precision intervals with millisecond +accuracy or below. + #### cancelTimer() The `cancelTimer(TimerInterface $timer): void` method can be used to diff --git a/src/LoopInterface.php b/src/LoopInterface.php index 9401922f..868d0a0c 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -179,6 +179,17 @@ public function removeWriteStream($stream); * Similarly, the execution order of timers scheduled to execute at the * same time (within its possible accuracy) is not guaranteed. * + * This interface suggests that event loop implementations SHOULD use a + * monotonic time source if available. Given that a monotonic time source is + * not available on PHP by default, event loop implementations MAY fall back + * to using wall-clock time. + * While this does not affect many common use cases, this is an important + * distinction for programs that rely on a high time precision or on systems + * that are subject to discontinuous time adjustments (time jumps). + * This means that if you schedule a timer to trigger in 30s and then adjust + * your system time forward by 20s, the timer SHOULD still trigger in 30s. + * See also [event loop implementations](#loop-implementations) for more details. + * * @param int|float $interval The number of seconds to wait before execution. * @param callable $callback The callback to invoke. * @@ -247,7 +258,7 @@ public function addTimer($interval, $callback); * same time (within its possible accuracy) is not guaranteed. * * This interface suggests that event loop implementations SHOULD use a - * monotic time source if available. Given that a monotonic time source is + * monotonic time source if available. Given that a monotonic time source is * not available on PHP by default, event loop implementations MAY fall back * to using wall-clock time. * While this does not affect many common use cases, this is an important @@ -257,6 +268,11 @@ public function addTimer($interval, $callback); * your system time forward by 20s, the timer SHOULD still trigger in 30s. * See also [event loop implementations](#loop-implementations) for more details. * + * Additionally, periodic timers may be subject to timer drift due to + * re-scheduling after each invocation. As such, it's generally not + * recommended to rely on this for high precision intervals with millisecond + * accuracy or below. + * * @param int|float $interval The number of seconds to wait before execution. * @param callable $callback The callback to invoke. * pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy