elisp: Timers
38.11 Timers for Delayed Execution
==================================
You can set up a “timer” to call a function at a specified future time
or after a certain length of idleness. A timer is a special object that
stores the information about the next invocation times and the function
to invoke.
-- Function: timerp object
This predicate function returns non-‘nil’ of ‘object’ is a timer.
Emacs cannot run timers at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
namely, while waiting or inside certain primitive functions such as
‘sit-for’ or ‘read-event’ which _can_ wait. Therefore, a timer’s
execution may be delayed if Emacs is busy. However, the time of
execution is very precise if Emacs is idle.
Emacs binds ‘inhibit-quit’ to ‘t’ before calling the timer function,
because quitting out of many timer functions can leave things in an
inconsistent state. This is normally unproblematical because most timer
functions don’t do a lot of work. Indeed, for a timer to call a
function that takes substantial time to run is likely to be annoying.
If a timer function needs to allow quitting, it should use
‘with-local-quit’ (
Quitting). For example, if a timer function
calls ‘accept-process-output’ to receive output from an external
process, that call should be wrapped inside ‘with-local-quit’, to ensure
that ‘C-g’ works if the external process hangs.
It is usually a bad idea for timer functions to alter buffer
contents. When they do, they usually should call ‘undo-boundary’ both
before and after changing the buffer, to separate the timer’s changes
from user commands’ changes and prevent a single undo entry from growing
to be quite large.
Timer functions should also avoid calling functions that cause Emacs
to wait, such as ‘sit-for’ (Waiting). This can lead to
unpredictable effects, since other timers (or even the same timer) can
run while waiting. If a timer function needs to perform an action after
a certain time has elapsed, it can do this by scheduling a new timer.
If a timer function calls functions that can change the match data,
it should save and restore the match data. Saving Match Data.
-- Command: run-at-time time repeat function &rest args
This sets up a timer that calls the function FUNCTION with
arguments ARGS at time TIME. If REPEAT is a number (integer or
floating point), the timer is scheduled to run again every REPEAT
seconds after TIME. If REPEAT is ‘nil’, the timer runs only once.
TIME may specify an absolute or a relative time.
Absolute times may be specified using a string with a limited
variety of formats, and are taken to be times _today_, even if
already in the past. The recognized forms are ‘XXXX’, ‘X:XX’, or
‘XX:XX’ (military time), and ‘XXam’, ‘XXAM’, ‘XXpm’, ‘XXPM’,
‘XX:XXam’, ‘XX:XXAM’, ‘XX:XXpm’, or ‘XX:XXPM’. A period can be
used instead of a colon to separate the hour and minute parts.
To specify a relative time as a string, use numbers followed by
units. For example:
‘1 min’
denotes 1 minute from now.
‘1 min 5 sec’
denotes 65 seconds from now.
‘1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year’
denotes exactly 103 months, 123 days, and 10862 seconds from
now.
For relative time values, Emacs considers a month to be exactly
thirty days, and a year to be exactly 365.25 days.
Not all convenient formats are strings. If TIME is a number
(integer or floating point), that specifies a relative time
measured in seconds. The result of ‘encode-time’ can also be used
to specify an absolute value for TIME.
In most cases, REPEAT has no effect on when _first_ call takes
place—TIME alone specifies that. There is one exception: if TIME
is ‘t’, then the timer runs whenever the time is a multiple of
REPEAT seconds after the epoch. This is useful for functions like
‘display-time’.
The function ‘run-at-time’ returns a timer value that identifies
the particular scheduled future action. You can use this value to
call ‘cancel-timer’ (see below).
A repeating timer nominally ought to run every 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 N seconds after the last invocation,
don’t use the REPEAT argument. Instead, the timer function should
explicitly reschedule the timer.
-- User Option: timer-max-repeats
This variable’s value specifies the maximum number of times to
repeat calling a timer function in a row, when many previously
scheduled calls were unavoidably delayed.
-- Macro: with-timeout (seconds timeout-forms...) body...
Execute BODY, but give up after SECONDS seconds. If BODY finishes
before the time is up, ‘with-timeout’ returns the value of the last
form in BODY. If, however, the execution of BODY is cut short by
the timeout, then ‘with-timeout’ executes all the TIMEOUT-FORMS and
returns the value of the last of them.
This macro works by setting a timer to run after SECONDS seconds.
If BODY finishes before that time, it cancels the timer. If the
timer actually runs, it terminates execution of BODY, then executes
TIMEOUT-FORMS.
Since timers can run within a Lisp program only when the program
calls a primitive that can wait, ‘with-timeout’ cannot stop
executing BODY while it is in the midst of a computation—only when
it calls one of those primitives. So use ‘with-timeout’ only with
a BODY that waits for input, not one that does a long computation.
The function ‘y-or-n-p-with-timeout’ provides a simple way to use a
timer to avoid waiting too long for an answer. Yes-or-No
Queries.
-- Function: cancel-timer timer
This cancels the requested action for TIMER, which should be a
timer—usually, one previously returned by ‘run-at-time’ or
‘run-with-idle-timer’. This cancels the effect of that call to one
of these functions; the arrival of the specified time will not
cause anything special to happen.
Info Catalog
elisp: Time Calculations
elisp: System Interface
elisp: Idle Timers