GNU Info

(elisp)Timers

---

Next: Terminal Input Prev: Time Conversion Up: System Interface

---

Enter node , (file) or (file)node

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.  Note: 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.