Skip to content

Documentation for high precision timers with millisecond accuracy or below #157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 26, 2018
Merged

Documentation for high precision timers with millisecond accuracy or below #157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a3d4bdd
Documentation for millisecond timer accuracy
clue Mar 25, 2018
f432daa
Documentation for timer drift for periodic timers
clue Mar 25, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 37 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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()

Expand Down
42 changes: 37 additions & 5 deletions src/LoopInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

@jsor jsor Mar 26, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference can probably omitted here in the docblock or link to README.md#loop-implementations

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point. This only consistently applies the same changes from #130 to this method. Does it make sense for you to keep this as-is for now and look into all these references in a follow-up PR? 👍

*
* @param int|float $interval The number of seconds to wait before execution.
* @param callable $callback The callback to invoke.
Expand Down Expand Up @@ -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
Expand All @@ -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.
*
Expand Down
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