diff options
Diffstat (limited to 'devdocs/elisp/timers.html')
| -rw-r--r-- | devdocs/elisp/timers.html | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/devdocs/elisp/timers.html b/devdocs/elisp/timers.html new file mode 100644 index 00000000..cb50697d --- /dev/null +++ b/devdocs/elisp/timers.html @@ -0,0 +1,25 @@ + <h3 class="section">Timers for Delayed Execution</h3> <p>You can set up a <em>timer</em> to call a function at a specified future time or after a certain length of idleness. A timer is a special object that stores the information about the next invocation times and the function to invoke. </p> <dl> <dt id="timerp">Function: <strong>timerp</strong> <em>object</em> +</dt> <dd><p>This predicate function returns non-<code>nil</code> if <code>object</code> is a timer. </p></dd> +</dl> <p>Emacs cannot run timers 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</code> or <code>read-event</code> which <em>can</em> 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. </p> <p>Emacs binds <code>inhibit-quit</code> to <code>t</code> before calling the timer function, because quitting out of many timer functions can leave 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. If a timer function needs to allow quitting, it should use <code>with-local-quit</code> (see <a href="quitting">Quitting</a>). For example, if a timer function calls <code>accept-process-output</code> to receive output from an external process, that call should be wrapped inside <code>with-local-quit</code>, to ensure that <kbd>C-g</kbd> works if the external process hangs. </p> <p>It is usually a bad idea for timer functions to alter buffer contents. When they do, they usually should call <code>undo-boundary</code> 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. </p> <p>Timer functions should also avoid calling functions that cause Emacs to wait, such as <code>sit-for</code> (see <a href="waiting">Waiting</a>). 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. </p> <p>If a timer function performs a remote file operation, it can be in conflict with an already running remote file operation of the same connection. Such conflicts are detected, and they result in a <code>remote-file-error</code> error (see <a href="standard-errors">Standard Errors</a>). This should be protected by wrapping the timer function body with </p> <div class="lisp"> <pre class="lisp">(ignore-error 'remote-file-error + …) +</pre> +</div> <p>If a timer function calls functions that can change the match data, it should save and restore the match data. See <a href="saving-match-data">Saving Match Data</a>. </p> <dl> <dt id="run-at-time">Command: <strong>run-at-time</strong> <em>time repeat function &rest args</em> +</dt> <dd> +<p>This sets up a timer that calls the function <var>function</var> with arguments <var>args</var> at time <var>time</var>. If <var>repeat</var> is a number (integer or floating point), the timer is scheduled to run again every <var>repeat</var> seconds after <var>time</var>. If <var>repeat</var> is <code>nil</code>, the timer runs only once. </p> <p><var>time</var> may specify an absolute or a relative time. </p> <p>Absolute times may be specified using a string with a limited variety of formats, and are taken to be times <em>today</em>, even if already in the past. The recognized forms are ‘<samp><var>xxxx</var></samp>’, ‘<samp><var>x</var>:<var>xx</var></samp>’, or ‘<samp><var>xx</var>:<var>xx</var></samp>’ (military time), and ‘<samp><var>xx</var>am</samp>’, ‘<samp><var>xx</var>AM</samp>’, ‘<samp><var>xx</var>pm</samp>’, ‘<samp><var>xx</var>PM</samp>’, ‘<samp><var>xx</var>:<var>xx</var>am</samp>’, ‘<samp><var>xx</var>:<var>xx</var>AM</samp>’, ‘<samp><var>xx</var>:<var>xx</var>pm</samp>’, or ‘<samp><var>xx</var>:<var>xx</var>PM</samp>’. A period can be used instead of a colon to separate the hour and minute parts. </p> <p>To specify a relative time as a string, use numbers followed by units. For example: </p> <dl compact> <dt>‘<samp>1 min</samp>’</dt> <dd><p>denotes 1 minute from now. </p></dd> <dt>‘<samp>1 min 5 sec</samp>’</dt> <dd><p>denotes 65 seconds from now. </p></dd> <dt>‘<samp>1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year</samp>’</dt> <dd><p>denotes exactly 103 months, 123 days, and 10862 seconds from now. </p></dd> </dl> <p>For relative time values, Emacs considers a month to be exactly thirty days, and a year to be exactly 365.25 days. </p> <p>Not all convenient formats are strings. If <var>time</var> is a number (integer or floating point), that specifies a relative time measured in seconds. The result of <code>encode-time</code> can also be used to specify an absolute value for <var>time</var>. </p> <p>In most cases, <var>repeat</var> has no effect on when <em>first</em> call takes place—<var>time</var> alone specifies that. There is one exception: if <var>time</var> is <code>t</code>, then the timer runs whenever the time is a multiple of <var>repeat</var> seconds after the epoch. This is useful for functions like <code>display-time</code>. </p> <p>If Emacs didn’t get any CPU time when the timer would have run (for example if the system was busy running another process or if the computer was sleeping or in a suspended state), the timer will run as soon as Emacs resumes and is idle. </p> <p>The function <code>run-at-time</code> returns a timer value that identifies the particular scheduled future action. You can use this value to call <code>cancel-timer</code> (see below). </p> +</dd> +</dl> <dl> <dt id="run-with-timer">Command: <strong>run-with-timer</strong> <em>secs repeat function &rest args</em> +</dt> <dd><p>This is exactly the same as <code>run-at-time</code> (so see that definition for an explanation of the parameters; <var>secs</var> is passed as <var>time</var> to that function), but is meant to be used when the delay is specified in seconds. </p></dd> +</dl> <p>A repeating timer nominally ought to run every <var>repeat</var> 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</var> seconds after the last invocation, don’t use the <var>repeat</var> argument. Instead, the timer function should explicitly reschedule the timer. </p> <dl> <dt id="timer-max-repeats">User Option: <strong>timer-max-repeats</strong> +</dt> <dd><p>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. </p></dd> +</dl> <dl> <dt id="with-timeout">Macro: <strong>with-timeout</strong> <em>(seconds timeout-forms…) body…</em> +</dt> <dd> +<p>Execute <var>body</var>, but give up after <var>seconds</var> seconds. If <var>body</var> finishes before the time is up, <code>with-timeout</code> returns the value of the last form in <var>body</var>. If, however, the execution of <var>body</var> is cut short by the timeout, then <code>with-timeout</code> executes all the <var>timeout-forms</var> and returns the value of the last of them. </p> <p>This macro works by setting a timer to run after <var>seconds</var> seconds. If <var>body</var> finishes before that time, it cancels the timer. If the timer actually runs, it terminates execution of <var>body</var>, then executes <var>timeout-forms</var>. </p> <p>Since timers can run within a Lisp program only when the program calls a primitive that can wait, <code>with-timeout</code> cannot stop executing <var>body</var> while it is in the midst of a computation—only when it calls one of those primitives. So use <code>with-timeout</code> only with a <var>body</var> that waits for input, not one that does a long computation. </p> +</dd> +</dl> <p>The function <code>y-or-n-p-with-timeout</code> provides a simple way to use a timer to avoid waiting too long for an answer. See <a href="yes_002dor_002dno-queries">Yes-or-No Queries</a>. </p> <dl> <dt id="cancel-timer">Function: <strong>cancel-timer</strong> <em>timer</em> +</dt> <dd><p>This cancels the requested action for <var>timer</var>, which should be a timer—usually, one previously returned by <code>run-at-time</code> or <code>run-with-idle-timer</code>. This cancels the effect of that call to one of these functions; the arrival of the specified time will not cause anything special to happen. </p></dd> +</dl> <p>The <code>list-timers</code> command lists all the currently active timers. The command <kbd>c</kbd> (<code>timer-list-cancel</code>) will cancel the timer on the line under point. You can sort the list by column using the command <kbd>S</kbd> (<code>tabulated-list-sort</code>). </p><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Timers.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Timers.html</a> + </p> +</div> |