diff lispref/os.texi @ 83542:2d56e13fd23d

Merged from [e-mail] Patches applied: * [e-mail]/emacs--devo--0--patch-413 Update from CVS * [e-mail]/emacs--devo--0--patch-414 Update from CVS * [e-mail]/emacs--devo--0--patch-415 Update from CVS * [e-mail]/emacs--devo--0--patch-416 Update from CVS * [e-mail]/emacs--devo--0--patch-417 Update from CVS * [e-mail]/emacs--devo--0--patch-418 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-419 Update from CVS * [e-mail]/emacs--devo--0--patch-420 Update from CVS * [e-mail]/emacs--devo--0--patch-421 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-422 Update from CVS * [e-mail]/emacs--devo--0--patch-423 Update from CVS * [e-mail]/emacs--devo--0--patch-424 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-425 Update from CVS * [e-mail]/emacs--devo--0--patch-426 Update from CVS * [e-mail]/emacs--devo--0--patch-427 Update from CVS * [e-mail]/emacs--devo--0--patch-428 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-429 Update from CVS * [e-mail]/emacs--devo--0--patch-430 Update from CVS * [e-mail]/emacs--devo--0--patch-431 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-432 Update from CVS * [e-mail]/emacs--devo--0--patch-433 Update from CVS * [e-mail]/emacs--devo--0--patch-434 Update from CVS * [e-mail]/emacs--devo--0--patch-435 Update from CVS * [e-mail]/emacs--devo--0--patch-436 Update from CVS * [e-mail]/emacs--devo--0--patch-437 Update from CVS * [e-mail]/emacs--devo--0--patch-438 Update from CVS * [e-mail]/emacs--devo--0--patch-439 Update from CVS * [e-mail]/emacs--devo--0--patch-440 Update from CVS * [e-mail]/emacs--devo--0--patch-441 lisp/url/url-methods.el: Fix format error when http_proxy is empty string * [e-mail]/emacs--devo--0--patch-442 Update from CVS * [e-mail]/emacs--devo--0--patch-443 Update from CVS * [e-mail]/emacs--devo--0--patch-444 Update from CVS * [e-mail]/emacs--devo--0--patch-445 Update from CVS * [e-mail]/emacs--devo--0--patch-446 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-447 Update from CVS * [e-mail]/emacs--devo--0--patch-448 Update from CVS * [e-mail]/emacs--devo--0--patch-449 Update from CVS * [e-mail]/emacs--devo--0--patch-450 Update from CVS * [e-mail]/emacs--devo--0--patch-451 Update from CVS * [e-mail]/emacs--devo--0--patch-452 Update from CVS * [e-mail]/emacs--devo--0--patch-453 Update from CVS * [e-mail]/emacs--devo--0--patch-454 Update from CVS * [e-mail]/emacs--devo--0--patch-455 Update from CVS * [e-mail]/emacs--devo--0--patch-456 Update from CVS * [e-mail]/emacs--devo--0--patch-457 Update from CVS * [e-mail]/emacs--devo--0--patch-458 Update from CVS * [e-mail]/emacs--devo--0--patch-459 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-460 Update from CVS * [e-mail]/emacs--devo--0--patch-461 Update from CVS * [e-mail]/emacs--devo--0--patch-462 Update from CVS * [e-mail]/emacs--devo--0--patch-463 Update from CVS * [e-mail]/emacs--devo--0--patch-464 Update from CVS * [e-mail]/emacs--devo--0--patch-465 Update from CVS * [e-mail]/emacs--devo--0--patch-466 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-467 Update from CVS * [e-mail]/emacs--devo--0--patch-468 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-469 Update from CVS * [e-mail]/emacs--devo--0--patch-470 Update from CVS * [e-mail]/emacs--devo--0--patch-471 Update from CVS * [e-mail]/emacs--devo--0--patch-472 Update from CVS * [e-mail]/emacs--devo--0--patch-473 Update from CVS * [e-mail]/gnus--rel--5.10--patch-128 Update from CVS * [e-mail]/gnus--rel--5.10--patch-129 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-130 Update from CVS * [e-mail]/gnus--rel--5.10--patch-131 Update from CVS * [e-mail]/gnus--rel--5.10--patch-132 Update from CVS * [e-mail]/gnus--rel--5.10--patch-133 Update from CVS * [e-mail]/gnus--rel--5.10--patch-134 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-135 Update from CVS * [e-mail]/gnus--rel--5.10--patch-136 Update from CVS * [e-mail]/gnus--rel--5.10--patch-137 Update from CVS * [e-mail]/gnus--rel--5.10--patch-138 Update from CVS * [e-mail]/gnus--rel--5.10--patch-139 Update from CVS * [e-mail]/gnus--rel--5.10--patch-140 Update from CVS * [e-mail]/gnus--rel--5.10--patch-141 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-142 Update from CVS * [e-mail]/gnus--rel--5.10--patch-143 Update from CVS * [e-mail]/gnus--rel--5.10--patch-144 Update from CVS * [e-mail]/gnus--rel--5.10--patch-145 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-146 Update from CVS * [e-mail]/gnus--rel--5.10--patch-147 Update from CVS * [e-mail]/gnus--rel--5.10--patch-148 Update from CVS * [e-mail]/gnus--rel--5.10--patch-149 Update from CVS git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-582

--- a/lispref/os.texi	Sat Oct 14 16:56:21 2006 +0000
+++ b/lispref/os.texi	Sat Oct 14 17:36:28 2006 +0000
@@ -1386,7 +1386,12 @@
 things in an inconsistent state.  This is normally unproblematical
 because most timer functions don't do a lot of work.  Indeed, for a
 timer to call a function that takes substantial time to run is likely
-to be annoying.
+to be annoying.  If a timer function needs to allow quitting, it
+should use @code{with-local-quit} (@pxref{Quitting}).  For example, if
+a timer function calls @code{accept-process-output} to receive output
+from an external process, that call should be wrapped inside
+@code{with-local-quit}, to ensure that @kbd{C-g} works if the external
+process hangs.
 
   It is usually a bad idea for timer functions to alter buffer
 contents.  When they do, they usually should call @code{undo-boundary}
@@ -1407,9 +1412,9 @@
 @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
-(integer or floating point), the timer also runs every @var{repeat}
-seconds after that.  If @var{repeat} is @code{nil}, the timer runs
-only once.
+(integer or floating point), the timer is scheduled to run again every
+@var{repeat} seconds after @var{time}.  If @var{repeat} is @code{nil},
+the timer runs only once.
 
 @var{time} may specify an absolute or a relative time.
 
@@ -1458,6 +1463,23 @@
 @code{cancel-timer} (see below).
 @end deffn
 
+  A repeating timer nominally ought to run every @var{repeat} seconds,
+but remember that any invocation of a timer can be late.  Lateness of
+one repetition has no effect on the scheduled time of the next
+repetition.  For instance, if Emacs is busy computing for long enough
+to cover three scheduled repetitions of the timer, and then starts to
+wait, it will immediately call the timer function three times in
+immediate succession (presuming no other timers trigger before or
+between them).  If you want a timer to run again no less than @var{n}
+seconds after the last invocation, don't use the @var{repeat} argument.
+Instead, the timer function should explicitly reschedule the timer.
+
+@defvar timer-max-repeats
+This variable's value specifies the maximum number of times to repeat
+calling a timer function in a row, when many previously scheduled
+calls were unavoidably delayed.
+@end defvar
+
 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
 Execute @var{body}, but give up after @var{seconds} seconds.  If
 @var{body} finishes before the time is up, @code{with-timeout} returns
@@ -1578,6 +1600,25 @@
 @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