From 85e56d97b717915509cb81c53238fbd06f390b92 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Fri, 3 Dec 2021 17:22:54 +0100 Subject: [PATCH] Clarify the run-at-time documentation about "integral multiple" * lisp/emacs-lisp/timer.el (run-at-time): * doc/lispref/os.texi (Timers): Explain what "integral multiple" really means. --- doc/lispref/os.texi | 8 +++++++- lisp/emacs-lisp/timer.el | 12 ++++++++++-- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index fb0f25fa3d7..e420644cd81 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -2183,7 +2183,13 @@ In most cases, @var{repeat} has no effect on when @emph{first} call takes place---@var{time} alone specifies that. There is one exception: if @var{time} is @code{t}, then the timer runs whenever the time is a multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. +functions like @code{display-time}. For instance, the following will +make @var{function} run at every ``whole'' minute (e.g., +@samp{11:03:00}, @samp{11:04:00}, etc): + +@example +(run-at-time t 60 @var{function}) +@end example If Emacs didn't get any CPU time when the timer would have run (for example if the system was busy running another process or if the diff --git a/lisp/emacs-lisp/timer.el b/lisp/emacs-lisp/timer.el index 1ef4931b7be..2ac2c992456 100644 --- a/lisp/emacs-lisp/timer.el +++ b/lisp/emacs-lisp/timer.el @@ -351,19 +351,27 @@ This function is called, by name, directly by the C code." Repeat the action every REPEAT seconds, if REPEAT is non-nil. REPEAT may be an integer or floating point number. TIME should be one of: + - a string giving today's time like \"11:23pm\" (the acceptable formats are HHMM, H:MM, HH:MM, HHam, HHAM, HHpm, HHPM, HH:MMam, HH:MMAM, HH:MMpm, or HH:MMPM; a period `.' can be used instead of a colon `:' to separate the hour and minute parts); + - a string giving a relative time like \"90\" or \"2 hours 35 minutes\" (the acceptable forms are a number of seconds without units or some combination of values using units in `timer-duration-words'); + - nil, meaning now; + - a number of seconds from now; + - a value from `encode-time'; -- or t (with non-nil REPEAT) meaning the next integral - multiple of REPEAT. + +- or t (with non-nil REPEAT) meaning the next integral multiple + of REPEAT. This is handy when you want the function to run at + a certain \"round\" number. For instance, (run-at-time t 60 ...) + will run at 11:04:00, 11:05:00, etc. The action is to call FUNCTION with arguments ARGS. -- 2.39.2