(Timers): Clarify about REPEAT when timer is delayed.

1 files changed, 14 insertions, 3 deletions

diff --git a/lispref/os.texi b/lispref/os.texi
index edf5833bf42..6c2d660709e 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -1407,9 +1407,9 @@ it should save and restore the match data.  @xref{Saving Match Data}.
 @deffn Command run-at-time time repeat function &rest args
 This sets up a timer that calls the function @var{function} with
 arguments @var{args} at time @var{time}.  If @var{repeat} is a number
-(integer or floating point), the timer also runs every @var{repeat}
-seconds after that.  If @var{repeat} is @code{nil}, the timer runs
-only once.
+(integer or floating point), the timer is scheduled to run again every
+@var{repeat} seconds after @var{time}.  If @var{repeat} is @code{nil},
+the timer runs only once.
 
 @var{time} may specify an absolute or a relative time.
 
@@ -1458,6 +1458,17 @@ the particular scheduled future action.  You can use this value to call
 @code{cancel-timer} (see below).
 @end deffn
 
+  A repeating timer nominally ought to run every @var{repeat} seconds,
+but remember that any invocation of a timer can be late.  Lateness of
+one repetition has no effect on the scheduled time of the next
+repetition.  For instance, if Emacs is busy computing for long enough
+to cover three scheduled repetitions of the timer, and then starts to
+wait, it will immediately call the timer function three times in
+immediate succession (presuming no other timers trigger before or
+between them).  If you want a timer to run again no less than @var{n}
+seconds after the last invocation, don't use the @var{repeat} argument.
+Instead, the timer function should explicitly reschedule the timer.
+
 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
 Execute @var{body}, but give up after @var{seconds} seconds.  If
 @var{body} finishes before the time is up, @code{with-timeout} returns