From 1558f3f49dc39df062d04fc753617ae3c43e8e17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Mon, 4 Dec 2017 12:37:19 +0100 Subject: [PATCH] Documentation for monotonic time source vs wall-clock time --- README.md | 22 +++++++++++++++++++++- src/LoopInterface.php | 11 +++++++++++ src/StreamSelectLoop.php | 9 +++++++++ 3 files changed, 41 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 27bb0bd3..48928dab 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ For the code of the current stable 0.4.x release, checkout the * [ExtLibeventLoop](#extlibeventloop) * [ExtLibevLoop](#extlibevloop) * [LoopInterface](#loopinterface) - * [addtimer()](#addtimer) + * [addTimer()](#addtimer) * [addPeriodicTimer()](#addperiodictimer) * [cancelTimer()](#canceltimer) * [isTimerActive()](#istimeractive) @@ -184,6 +184,15 @@ It is commonly installed as part of many PHP distributions. If this extension is missing (or you're running on Windows), signal handling is not supported and throws a `BadMethodCallException` instead. +This event loop is known to rely on wall-clock time to schedule future +timers, because a monotonic time source is not available in PHP by default. +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 may trigger in 10s. +See also [`addTimer()`](#addtimer) for more details. + #### ExtEventLoop An `ext-event` based event loop. @@ -267,6 +276,17 @@ hello('Tester', $loop); The execution order of timers scheduled to execute at the same time 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 +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. + #### addPeriodicTimer() The `addPeriodicTimer(float $interval, callable $callback): TimerInterface` method can be used to diff --git a/src/LoopInterface.php b/src/LoopInterface.php index 57783fab..e91b856e 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -224,6 +224,17 @@ public function addTimer($interval, callable $callback); * The execution order of timers scheduled to execute at the same time 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 + * 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. * diff --git a/src/StreamSelectLoop.php b/src/StreamSelectLoop.php index af46ea23..e556d8b3 100644 --- a/src/StreamSelectLoop.php +++ b/src/StreamSelectLoop.php @@ -39,6 +39,15 @@ * If this extension is missing (or you're running on Windows), signal handling is * not supported and throws a `BadMethodCallException` instead. * + * This event loop is known to rely on wall-clock time to schedule future + * timers, because a monotonic time source is not available in PHP by default. + * 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 may trigger in 10s. + * See also [`addTimer()`](#addtimer) for more details. + * * @link http://php.net/manual/en/function.stream-select.php */ class StreamSelectLoop implements LoopInterface 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