*** empty log message ***

[gnu-emacs] / lispref / os.texi

diff --git a/lispref/os.texi b/lispref/os.texi
index 65510197e4e30323c17db179117febdcf3918b95..edf5833bf42e488962645ed5fc05f45de2cdc045 100644 (file)
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -1394,6 +1394,13 @@ both before and after changing the buffer, to separate the timer's
 changes from user commands' changes and prevent a single undo entry
 from growing to be quite large.
 
+  Timer functions should also avoid calling functions that cause Emacs
+to wait, such as @code{sit-for} (@pxref{Waiting}).  This can lead to
+unpredictable effects, since other timers (or even the same timer) can
+run while waiting.  If a timer function needs to perform an action
+after a certain time has elapsed, it can do this by scheduling a new
+timer.
+
   If a timer function calls functions that can change the match data,
 it should save and restore the match data.  @xref{Saving Match Data}.
 
@@ -1487,13 +1494,14 @@ cause anything special to happen.
 @section Idle Timers
 
   Here is how to set up a timer that runs when Emacs is idle for a
-certain length of time.  Aside from how to set them nup, idle timers
+certain length of time.  Aside from how to set them up, idle timers
 work just like ordinary timers.
 
 @deffn Command run-with-idle-timer secs repeat function &rest args
 Set up a timer which runs when Emacs has been idle for @var{secs}
 seconds.  The value of @var{secs} may be an integer or a floating point
-number.
+number; a value of the type returned by @code{current-idle-time}
+is also allowed.
 
 If @var{repeat} is @code{nil}, the timer runs just once, the first time
 Emacs remains idle for a long enough time.  More often @var{repeat} is
@@ -1501,7 +1509,7 @@ non-@code{nil}, which means to run the timer @emph{each time} Emacs
 remains idle for @var{secs} seconds.
 
 The function @code{run-with-idle-timer} returns a timer value which you
-can use in calling @code{cancel-timer} (see below).
+can use in calling @code{cancel-timer} (@pxref{Timers}).
 @end deffn
 
 @cindex idleness
@@ -1561,7 +1569,7 @@ Here's an example:
   (when @var{taking-a-break}
     (setq resume-timer
           (run-with-idle-timer
-            ;; Compute an idle time @var{break-length} 
+            ;; Compute an idle time @var{break-length}
             ;; more than the current value.
             (time-add (current-idle-time)
                       (seconds-to-time @var{break-length}))
@@ -1570,6 +1578,25 @@ Here's an example:
 @end smallexample
 @end defun
 
+  Some idle timer functions in user Lisp packages have a loop that
+does a certain amount of processing each time around, and exits when
+@code{(input-pending-p)} is non-@code{nil}.  That approach seems very
+natural but has two problems:
+
+@itemize
+@item
+It blocks out all process output (since Emacs accepts process output
+only while waiting).
+
+@item
+It blocks out any idle timers that ought to run during that time.
+@end itemize
+
+@noindent
+To avoid these problems, don't use that technique.  Instead, write
+such idle timers to reschedule themselves after a brief pause, using
+the method in the @code{timer-function} example above.
+
 @node Terminal Input
 @section Terminal Input
 @cindex terminal input