Fix bugs #12447 and #12326 with infloop causes by idle timers, update docs.

 src/keyboard.c (timer_check_2): Move calculation of 'timers' and
 'idle_timers' from here ...
 (timer_check): ... to here.  Use Fcopy_sequence to copy the timer
 lists, to avoid infloops when the timer does something stupid,
 like reinvoke itself with the same or smaller time-out.

 lisp/emacs-lisp/timer.el (run-with-idle-timer)
 (timer-activate-when-idle): Warn against reinvoking an idle timer
 from within its own timer action.

 doc/lispref/os.texi (Idle Timers): Warn against reinvoking an idle timer
 from within its own timer action.

1 files changed, 12 insertions, 3 deletions

diff --git a/lisp/emacs-lisp/timer.el b/lisp/emacs-lisp/timer.el
index 2248dde8c03..bcd582a6f88 100644
--- a/lisp/emacs-lisp/timer.el
+++ b/lisp/emacs-lisp/timer.el
@@ -205,12 +205,19 @@ timers).  If nil, allocate a new 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, or at the right time, if Emacs is already idle.
+immediately \(see beloe\), 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."
+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))
 
 (defalias 'disable-timeout 'cancel-timer)
@@ -403,7 +410,9 @@ 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.
+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).