40.7 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.

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.

Function: run-at-time time repeat function &rest args

This function arranges to call function with arguments args at time time. The argument function is a function to call later, and args are the arguments to give it when it is called. The time time is specified as a string.

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:

`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.

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).

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. See section 20.6 Yes-or-No Queries.

Function: run-with-idle-timer secs repeat function &rest args

Set up a timer which runs when Emacs has been idle for secs seconds. The value of secs may be an integer or a floating point number.

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 becomes idle. Even if repeat is non-nil, 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, and 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.

Function: cancel-timer timer

Cancel the requested action for timer, which should be a value previously returned by 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.