@@ -168,8 +168,27 @@ public function removeWriteStream($stream);
168
168
* hello('Tester', $loop);
169
169
* ```
170
170
*
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.
173
192
*
174
193
* @param int|float $interval The number of seconds to wait before execution.
175
194
* @param callable $callback The callback to invoke.
@@ -227,11 +246,19 @@ public function addTimer($interval, $callback);
227
246
* hello('Tester', $loop);
228
247
* ```
229
248
*
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.
232
259
*
233
260
* 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
235
262
* not available on PHP by default, event loop implementations MAY fall back
236
263
* to using wall-clock time.
237
264
* While this does not affect many common use cases, this is an important
@@ -241,6 +268,11 @@ public function addTimer($interval, $callback);
241
268
* your system time forward by 20s, the timer SHOULD still trigger in 30s.
242
269
* See also [event loop implementations](#loop-implementations) for more details.
243
270
*
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
+ *
244
276
* @param int|float $interval The number of seconds to wait before execution.
245
277
* @param callable $callback The callback to invoke.
246
278
*
0 commit comments