Documentation for millisecond timer accuracy

clue · clue · commit a3d4bdd5f647 · 2018-03-25T19:58:34.000+02:00
diff --git 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
@@ -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
