Skip to content

Commit 1e7d9a6

Browse files
authored
Merge pull request #157 from clue-labs/accuracy
Documentation for high precision timers with millisecond accuracy or below
2 parents b94bc8e + f432daa commit 1e7d9a6

File tree

2 files changed

+74
-10
lines changed

2 files changed

+74
-10
lines changed

README.md

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -281,11 +281,19 @@ function hello($name, LoopInterface $loop)
281281
hello('Tester', $loop);
282282
```
283283

284-
The execution order of timers scheduled to execute at the same time is
285-
not guaranteed.
284+
This interface does not enforce any particular timer resolution, so
285+
special care may have to be taken if you rely on very high precision with
286+
millisecond accuracy or below. Event loop implementations SHOULD work on
287+
a best effort basis and SHOULD provide at least millisecond accuracy
288+
unless otherwise noted. Many existing event loop implementations are
289+
known to provide microsecond accuracy, but it's generally not recommended
290+
to rely on this high precision.
291+
292+
Similarly, the execution order of timers scheduled to execute at the
293+
same time (within its possible accuracy) is not guaranteed.
286294

287295
This interface suggests that event loop implementations SHOULD use a
288-
monotic time source if available. Given that a monotonic time source is
296+
monotonic time source if available. Given that a monotonic time source is
289297
not available on PHP by default, event loop implementations MAY fall back
290298
to using wall-clock time.
291299
While this does not affect many common use cases, this is an important
@@ -346,8 +354,32 @@ function hello($name, LoopInterface $loop)
346354
hello('Tester', $loop);
347355
```
348356

349-
The execution order of timers scheduled to execute at the same time is
350-
not guaranteed.
357+
This interface does not enforce any particular timer resolution, so
358+
special care may have to be taken if you rely on very high precision with
359+
millisecond accuracy or below. Event loop implementations SHOULD work on
360+
a best effort basis and SHOULD provide at least millisecond accuracy
361+
unless otherwise noted. Many existing event loop implementations are
362+
known to provide microsecond accuracy, but it's generally not recommended
363+
to rely on this high precision.
364+
365+
Similarly, the execution order of timers scheduled to execute at the
366+
same time (within its possible accuracy) is not guaranteed.
367+
368+
This interface suggests that event loop implementations SHOULD use a
369+
monotonic time source if available. Given that a monotonic time source is
370+
not available on PHP by default, event loop implementations MAY fall back
371+
to using wall-clock time.
372+
While this does not affect many common use cases, this is an important
373+
distinction for programs that rely on a high time precision or on systems
374+
that are subject to discontinuous time adjustments (time jumps).
375+
This means that if you schedule a timer to trigger in 30s and then adjust
376+
your system time forward by 20s, the timer SHOULD still trigger in 30s.
377+
See also [event loop implementations](#loop-implementations) for more details.
378+
379+
Additionally, periodic timers may be subject to timer drift due to
380+
re-scheduling after each invocation. As such, it's generally not
381+
recommended to rely on this for high precision intervals with millisecond
382+
accuracy or below.
351383

352384
#### cancelTimer()
353385

src/LoopInterface.php

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -168,8 +168,27 @@ public function removeWriteStream($stream);
168168
* hello('Tester', $loop);
169169
* ```
170170
*
171-
* The execution order of timers scheduled to execute at the same time is
172-
* not guaranteed.
171+
* This interface does not enforce any particular timer resolution, so
172+
* special care may have to be taken if you rely on very high precision with
173+
* millisecond accuracy or below. Event loop implementations SHOULD work on
174+
* a best effort basis and SHOULD provide at least millisecond accuracy
175+
* unless otherwise noted. Many existing event loop implementations are
176+
* known to provide microsecond accuracy, but it's generally not recommended
177+
* to rely on this high precision.
178+
*
179+
* Similarly, the execution order of timers scheduled to execute at the
180+
* same time (within its possible accuracy) is not guaranteed.
181+
*
182+
* This interface suggests that event loop implementations SHOULD use a
183+
* monotonic time source if available. Given that a monotonic time source is
184+
* not available on PHP by default, event loop implementations MAY fall back
185+
* to using wall-clock time.
186+
* While this does not affect many common use cases, this is an important
187+
* distinction for programs that rely on a high time precision or on systems
188+
* that are subject to discontinuous time adjustments (time jumps).
189+
* This means that if you schedule a timer to trigger in 30s and then adjust
190+
* your system time forward by 20s, the timer SHOULD still trigger in 30s.
191+
* See also [event loop implementations](#loop-implementations) for more details.
173192
*
174193
* @param int|float $interval The number of seconds to wait before execution.
175194
* @param callable $callback The callback to invoke.
@@ -227,11 +246,19 @@ public function addTimer($interval, $callback);
227246
* hello('Tester', $loop);
228247
* ```
229248
*
230-
* The execution order of timers scheduled to execute at the same time is
231-
* not guaranteed.
249+
* This interface does not enforce any particular timer resolution, so
250+
* special care may have to be taken if you rely on very high precision with
251+
* millisecond accuracy or below. Event loop implementations SHOULD work on
252+
* a best effort basis and SHOULD provide at least millisecond accuracy
253+
* unless otherwise noted. Many existing event loop implementations are
254+
* known to provide microsecond accuracy, but it's generally not recommended
255+
* to rely on this high precision.
256+
*
257+
* Similarly, the execution order of timers scheduled to execute at the
258+
* same time (within its possible accuracy) is not guaranteed.
232259
*
233260
* This interface suggests that event loop implementations SHOULD use a
234-
* monotic time source if available. Given that a monotonic time source is
261+
* monotonic time source if available. Given that a monotonic time source is
235262
* not available on PHP by default, event loop implementations MAY fall back
236263
* to using wall-clock time.
237264
* While this does not affect many common use cases, this is an important
@@ -241,6 +268,11 @@ public function addTimer($interval, $callback);
241268
* your system time forward by 20s, the timer SHOULD still trigger in 30s.
242269
* See also [event loop implementations](#loop-implementations) for more details.
243270
*
271+
* Additionally, periodic timers may be subject to timer drift due to
272+
* re-scheduling after each invocation. As such, it's generally not
273+
* recommended to rely on this for high precision intervals with millisecond
274+
* accuracy or below.
275+
*
244276
* @param int|float $interval The number of seconds to wait before execution.
245277
* @param callable $callback The callback to invoke.
246278
*

0 commit comments

Comments
 (0)