From 0c1241267e595c397a812bc0afa93d7209768f94 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Tue, 23 Jul 1996 15:40:25 +0000 Subject: [PATCH] Lots of timer feature updates. encode-time takes additional arguments and ignores them. Change linux to gnu/linux for system-type. More information about key translation features. --- lispref/os.texi | 133 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 112 insertions(+), 21 deletions(-) diff --git a/lispref/os.texi b/lispref/os.texi index f941b3bfb0..e231a0937a 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -566,7 +566,10 @@ Berkeley BSD. Data General DGUX operating system. @item gnu -A GNU system using the GNU HURD and Mach. +A GNU system (using the GNU kernel, which consists of the HURD and Mach). + +@item gnu/linux +A variant GNU system using the Linux kernel. @item hpux Hewlett-Packard HPUX operating system. @@ -574,9 +577,6 @@ Hewlett-Packard HPUX operating system. @item irix Silicon Graphics Irix system. -@item linux -A GNU system using the Linux kernel. - @item ms-dos Microsoft MS-DOS ``operating system.'' @@ -1023,7 +1023,7 @@ Note that Common Lisp has different meanings for @var{dow} and @var{zone}. @end defun -@defun encode-time seconds minutes hour day month year &optional zone +@defun encode-time seconds minutes hour day month year &optional @dots{}zone This function is the inverse of @code{decode-time}. It converts seven items of calendrical data into a time value. For the meanings of the arguments, see the table above under @code{decode-time}. @@ -1037,12 +1037,31 @@ its daylight savings time rules. If specified, it can be either a list (as you would get from @code{current-time-zone}) or an integer (as you would get from @code{decode-time}). The specified zone is used without any further alteration for daylight savings time. + +If you pass more than seven arguments to @code{encode-time}, the first +six are used as @var{seconds} through @var{year}, the last argument is +used as @var{zone}, and the arguments in between are ignored. This +feature makes it possible to use the elements of a list returned by +@code{decode-time} as the arguments to @code{encode-time}, like this: + +@example +(apply 'encode-time (decode-time @dots{})) +@end example @end defun @node Timers @section Timers for Delayed Execution +@cindex timer -You can set up a timer to call a function at a specified future time. + You can set up a @dfn{timer} to call a function at a specified future time or +after a certain length of idleness. + + Emacs cannot run a timer at any arbitrary point in a Lisp program; it +can run them only when Emacs could accept output from a subprocess: +namely, while waiting or inside certain primitive functions such as +@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a +timer's execution may be delayed if Emacs is busy. However, the time of +execution is very precise if Emacs is idle. @defun run-at-time time repeat function &rest args This function arranges to call @var{function} with arguments @var{args} @@ -1050,7 +1069,7 @@ at time @var{time}. The argument @var{function} is a function to call later, and @var{args} are the arguments to give it when it is called. The time @var{time} is specified as a string. -Absolute times may be specified in a wide variety of formats; The form +Absolute times may be specified in a variety of formats; The form @samp{@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}}, where all fields are numbers, works; the format that @code{current-time-string} returns is also allowed. @@ -1067,26 +1086,85 @@ denotes 65 seconds from now. denotes exactly 103 months, 123 days, and 10862 seconds from now. @end table -If @var{time} is an integer, that specifies a relative time measured in -seconds. +If @var{time} is a number (integer or floating point), that specifies a +relative time measured in seconds. The argument @var{repeat} specifies how often to repeat the call. If @var{repeat} is @code{nil}, there are no repetitions; @var{function} is -called just once, at @var{time}. If @var{repeat} is an integer, it -specifies a repetition period measured in seconds. In any case, @var{repeat} -has no effect on when @emph{first} call takes place---@var{time} specifies -that. +called just once, at @var{time}. If @var{repeat} is a number, it +specifies a repetition period measured in seconds. In any case, +@var{repeat} has no effect on when @emph{first} call takes +place---@var{time} alone specifies that. The function @code{run-at-time} returns a timer value that identifies the particular scheduled future action. You can use this value to call -@code{cancel-timer}. +@code{cancel-timer} (see below). +@end defun + +@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 +the value of the last form in @var{body}. If, however, the execution of +@var{body} is cut short by the timeout, then @code{with-timeout} +executes all the @var{timeout-forms} and returns the value of the last +of them. + +This macro works by set a timer to run after @var{seconds} seconds. If +@var{body} finishes before that time, it cancels the timer. If the +timer actually runs, it terminates execution of @var{body}, then +executes @var{timeout-forms}. + +Since timers can run within a Lisp program only when the program calls a +primitive that can wait, @code{with-timeout} cannot stop executing +@var{body} while it is in the midst of a computation---only when it +calls one of those primitives. So use @code{with-timeout} only with a +@var{body} that waits for input, not one that does a long computation. +@end defmac + + The function @code{y-or-n-p-with-timeout} provides a simple way to use +a timer to avoid waiting too long for an answer. @xref{Yes-or-No +Queries}. + +@defun 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. + +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 +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). @end defun +@cindex idleness + Emacs becomes ``idle'' when it starts waiting for user input, and it +remains idle until the user provides some input. If a timer is set for +five seconds of idleness, it runs approximately five seconds after Emacs +first became idle. Even if its @var{repeat} is true, this timer will +not run again as long as Emacs remains idle, because the duration of +idleness will continue to increase and will not go down to five seconds +again. + + Emacs can do various things while idle: garbage collect, autosave or +handle data from a subprocess. But these interludes during idleness +have little effect on idle timers. An idle timer set for 600 seconds +will run when ten minutes have elapsed since the last user command was +finished, even if subprocess output has been accepted thousands of times +within those ten minutes, even if there have been garbage collections +and autosaves. + + When the user supplies input, Emacs becomes non-idle while executing the +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. + @defun cancel-timer timer Cancel the requested action for @var{timer}, which should be a value -previously returned by @code{run-at-time}. This cancels the effect of -that call to @code{run-at-time}; the arrival of the specified time will -not cause anything special to happen. +previously returned by @code{run-at-time} or @code{run-with-idle-timer}. +This cancels the effect of that call to @code{run-at-time}; the arrival +of the specified time will not cause anything special to happen. @end defun @node Terminal Input @@ -1169,8 +1247,14 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}. @subsection Translating Input Events @cindex translating input events - This section describes features for translating input events into other -input events before they become part of key sequences. + This section describes features for translating input events into +other input events before they become part of key sequences. These +features apply to each event in the order they are described here: each +event is first modified according to @code{extra-keyboard-modifiers}, +then translated through @code{keyboard-translate-table} (if applicable). +If it is being read as part of a key sequence, it is then added to the +sequece being read; then subsequences containing it are checked first +with @code{function-key-map} and then with @code{key-translation-map}. @c Emacs 19 feature @defvar extra-keyboard-modifiers @@ -1250,11 +1334,15 @@ character code @var{from} into character code @var{to}. It creates or enlarges the translate table if necessary. @end defun + The remaining translation features translate subsequences of key +sequences being read. They are implemented in @code{read-key-sequence} +and have no effect on @code{read-char}. + @defvar function-key-map This variable holds a keymap that describes the character sequences sent by function keys on an ordinary character terminal. This keymap uses the same data structure as other keymaps, but is used differently: it -specifies translations to make while reading events. +specifies translations to make while reading event sequences. If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a @@ -1299,7 +1387,10 @@ finished; it receives the results of translation by @code{function-key-map}. @item -@code{key-translation-map} overrides actual key bindings. +@code{key-translation-map} overrides actual key bindings. For example, +if @kbd{C-x f} has a binding in @code{key-translation-map}, that +translation takes effect even though @kbd{C-x f} also has a key binding +in the global map. @end itemize The intent of @code{key-translation-map} is for users to map one -- 2.20.1