Function: timer-activate-when-idle

timer-activate-when-idle is a byte-compiled function defined in timer.el.gz.

Signature

(timer-activate-when-idle TIMER &optional DONT-WAIT REUSE-CELL)

Documentation

Insert TIMER into timer-idle-list.

This arranges to activate TIMER whenever Emacs is next idle. If optional argument DONT-WAIT is non-nil, set TIMER to activate immediately (see below), or at the right time, if Emacs is already idle.

REUSE-CELL, if non-nil, is a cons cell to reuse when inserting TIMER into timer-idle-list (usually a cell removed from that list by cancel-timer-internal; using this reduces consing for repeat timers). If nil, allocate a new cell.

Using non-nil DONT-WAIT is not recommended when activating an idle timer from an idle timer handler, if the timer being activated has an idleness time that is smaller or equal to the time of the current timer. That's because the activated timer will fire right away.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/timer.el.gz
(defun timer-activate-when-idle (timer &optional dont-wait reuse-cell)
  "Insert TIMER into `timer-idle-list'.
This arranges to activate TIMER whenever Emacs is next idle.
If optional argument DONT-WAIT is non-nil, set TIMER to activate
immediately \(see below), or at the right time, if Emacs is
already idle.

REUSE-CELL, if non-nil, is a cons cell to reuse when inserting
TIMER into `timer-idle-list' (usually a cell removed from that
list by `cancel-timer-internal'; using this reduces consing for
repeat timers).  If nil, allocate a new cell.

Using non-nil DONT-WAIT is not recommended when activating an
idle timer from an idle timer handler, if the timer being
activated has an idleness time that is smaller or equal to
the time of the current timer.  That's because the activated
timer will fire right away."
  (timer--activate timer (not dont-wait) reuse-cell 'idle))