---

I.2.5.1 Timer Functions and Commands

Function timerp OBJECT

Function: timerp OBJECT ¶

This predicate function returns non-nil if object is a timer.

Command run-at-time

Function: run-at-time TIME REPEAT FUNCTION &rest ARGS ¶

This sets up a timer that calls the function ‘FUNCTION’ with arguments ‘ARGS’ at time ‘TIME’.

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
  • xx:xx
  • xxam
  • xxAM
  • xxpm
  • xxPM
  • xx:xxam
  • xx:xxAM
  • xx:xxpm
  • xx:xxPM
• The result of encode-time can also be used to specify an absolute value for time.
• To specify a relative time as a string, use numbers followed by units.
  • ‘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.

REPEAT

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.

Any invocation of a timer can be late. Lateness of one repetition has no effect on the scheduled time of the next repetition. 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.

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.

Return Value

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.

Command run-with-timer

Function: run-with-timer SECS REPEAT FUNCTION &rest ARGS ¶

This is exactly the same as run-at-time (so see that definition for an explanation of the parameters; ‘SECS’ is passed as ‘TIME’ to that function), but is meant to be used when the delay is specified in seconds.

User Option timer-max-repeats

Variable: 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

Function: with-timeout (SECONDS TIMEOUT-FORMS...) BODY ¶

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

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.

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.

Function cancel-timer

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.

Command list-timers

Function: list-timers &optional IGNORE-AUTO NONCONFIRM ¶

The list-timers command¹¹ lists all the currently active timers.

There’s only one command available in the buffer displayed: ‘c’ (timer-list-cancel) that will cancel the timer on the line under point.