# HG changeset patch
# User Richard M. Stallman <rms@gnu.org>
# Date 1104351057 0
# Node ID 6142d449ffb88ad78c321dc46c907f18d865b46a
# Parent  60ffced085328e53f98ed929080d669ded1b3456
(Timers): Discuss timers vs editing the buffer and undo.

diff -r 60ffced08532 -r 6142d449ffb8 lispref/os.texi
--- a/lispref/os.texi	Wed Dec 29 17:25:02 2004 +0000
+++ b/lispref/os.texi	Wed Dec 29 20:10:57 2004 +0000
@@ -1368,6 +1368,11 @@
 timer to call a function that takes substantial time to run is likely
 to be annoying.
 
+  Timer functions should normally not alter the current buffer
+contents, but it may be ok to alter some other buffer that exists for
+special purposes.  A general guideline is that if a buffer has undo
+enabled, timers should not write in it.
+
 @deffn Command run-at-time time repeat function &rest args
 This sets up a timer that calls the function @var{function} with
 arguments @var{args} at time @var{time}.  If @var{repeat} is a number
@@ -1481,6 +1486,11 @@
 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.
 
+  It is legitimate for an idle timer to edit the current buffer.  If
+it does, it should explicitly call @code{undo-boundary} once at the
+beginning and once just before exiting, since Emacs won't do that
+automatically for an idle timer.
+
 @defun cancel-timer timer
 Cancel the requested action for @var{timer}, which should be a value
 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.