diff --git a/README.md b/README.md index 5ee4d8e5..6912e021 100644 --- a/README.md +++ b/README.md @@ -281,11 +281,19 @@ 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 +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 @@ -346,8 +354,32 @@ 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 +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() diff --git a/src/LoopInterface.php b/src/LoopInterface.php index ebf58755..868d0a0c 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -168,8 +168,27 @@ 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. + * + * 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. @@ -227,11 +246,19 @@ 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 + * 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 @@ -241,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