From 467859c2ba0beadbb536ebde919e3883c7b4bc11 Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Sun, 8 Dec 2024 22:32:49 +0100 Subject: [PATCH] doc: clarify repeating timer behavior more (#4640) It was already documented but only in the uv_timer_set_repeat section. Move it to the toplevel and flesh it out more. Refs: https://github.com/libuv/libuv/issues/181 Refs: https://github.com/libuv/libuv/discussions/4639 --- docs/src/timer.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/src/timer.rst b/docs/src/timer.rst index 070fa79d..474c6b8c 100644 --- a/docs/src/timer.rst +++ b/docs/src/timer.rst @@ -6,6 +6,15 @@ Timer handles are used to schedule callbacks to be called in the future. +Timers are either single-shot or repeating. Repeating timers do not adjust +for overhead but are rearmed relative to the event loop's idea of "now". + +Libuv updates its idea of "now" right before executing timer callbacks, and +right after waking up from waiting for I/O. See also :c:func:`uv_update_time`. + +Example: a repeating timer with a 50 ms interval whose callback takes 17 ms +to complete, runs again 33 ms later. If other tasks take longer than 33 ms, +the timer callback runs as soon as possible. Data types ---------- @@ -64,11 +73,6 @@ API duration, and will follow normal timer semantics in the case of a time-slice overrun. - For example, if a 50ms repeating timer first runs for 17ms, it will be - scheduled to run again 33ms later. If other tasks consume more than the - 33ms following the first timer callback, then the callback will run as soon - as possible. - .. note:: If the repeat value is set from a timer callback it does not immediately take effect. If the timer was non-repeating before, it will have been stopped. If it was repeating,