Function: run-with-idle-timer

run-with-idle-timer is an interactive and byte-compiled function defined in timer.el.gz.

Signature

(run-with-idle-timer SECS REPEAT FUNCTION &rest ARGS)

Documentation

Perform an action the next time Emacs is idle for SECS seconds.

The action is to call FUNCTION with arguments ARGS. SECS may be an integer, a floating point number, or the internal time format returned by, e.g., current-idle-time. If Emacs is currently idle, and has been idle for N seconds (N < SECS), then it will call FUNCTION in SECS - N seconds from now. Using SECS <= N is not recommended if this function is invoked from an idle timer, because FUNCTION will then be called immediately.

If REPEAT is non-nil, do the action each time Emacs has been idle for exactly SECS seconds (that is, only once for each time Emacs becomes idle).

This function returns a timer object which you can use in cancel-timer.

View in manual

Probably introduced at or before Emacs version 19.31.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/timer.el.gz
(defun run-with-idle-timer (secs repeat function &rest args)
  "Perform an action the next time Emacs is idle for SECS seconds.
The action is to call FUNCTION with arguments ARGS.
SECS may be an integer, a floating point number, or the internal
time format returned by, e.g., `current-idle-time'.
If Emacs is currently idle, and has been idle for N seconds (N < SECS),
then it will call FUNCTION in SECS - N seconds from now.  Using
SECS <= N is not recommended if this function is invoked from an idle
timer, because FUNCTION will then be called immediately.

If REPEAT is non-nil, do the action each time Emacs has been idle for
exactly SECS seconds (that is, only once for each time Emacs becomes idle).

This function returns a timer object which you can use in `cancel-timer'."
  (interactive
   (list (read-from-minibuffer "Run after idle (seconds): " nil nil t)
	 (y-or-n-p "Repeat each time Emacs is idle? ")
	 (intern (completing-read "Function: " obarray #'fboundp t))))
  (let ((timer (timer-create)))
    (timer-set-function timer function args)
    (timer-set-idle-time timer secs repeat)
    (timer-activate-when-idle timer t)
    timer))