You can set up a timer to call a function at a specified future time or after a certain length of idleness.
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.
Absolute times may be specified in a wide variety of formats; this function tries to accept all the commonly used date formats. Valid formats include these two,
year-month-day hour:min:sec timezone hour:min:sec timezone month/day/year
where in both examples all fields are numbers; the format that
current-time-string returns is also allowed, and many others
as well.
To specify a relative time, use numbers followed by units. For example:
If time is a number (integer or floating point), that specifies a relative time measured in seconds.
The argument repeat specifies how often to repeat the call. If
repeat is nil, there are no repetitions; function is
called just once, at time. If repeat is a number, it
specifies a repetition period measured in seconds.
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).
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. See section Yes-or-No Queries.
If repeat is nil, the timer runs just once, the first time
Emacs remains idle for a long enough time. More often repeat is
non-nil, which means to run the timer each time Emacs
remains idle for secs seconds.
The function run-with-idle-timer returns a timer value which you
can use in calling cancel-timer (see below).
Emacs becomes "idle" when it starts waiting for user input, and it remains idle until the user provides some input. If a timer is set for five seconds of idleness, it runs approximately five seconds after Emacs first became idle. Even if its repeat is true, this timer will not run again as long as Emacs remains idle, because the duration of idleness will continue to increase and will not go down to five seconds again.
Emacs can do various things while idle: garbage collect, autosave or handle data from a subprocess. But these interludes during idleness do not interfere with idle timers, because they do not reset the clock of idleness to zero. An idle timer set for 600 seconds will run when ten minutes have elapsed since the last user command was finished, even if subprocess output has been accepted thousands of times within those ten minutes, even if there have been garbage collections and autosaves.
When the user supplies input, Emacs becomes non-idle while executing the input. Then it becomes idle again, and all the idle timers that are set up to repeat will subsequently run another time, one by one.
run-at-time or run-with-idle-timer.
This cancels the effect of that call to run-at-time; the arrival
of the specified time will not cause anything special to happen.
Go to the first, previous, next, last section, table of contents.