Commit | Line | Data |
---|---|---|
c4ba2209 | 1 | ;;; timer.el --- run a function with args at some time in future. |
d501f516 | 2 | |
4395bfdb | 3 | ;; Copyright (C) 1996 Free Software Foundation, Inc. |
5cc564a6 | 4 | |
eea8d4ef ER |
5 | ;; Maintainer: FSF |
6 | ||
5cc564a6 | 7 | ;; This file is part of GNU Emacs. |
8 | ||
9 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
10 | ;; it under the terms of the GNU General Public License as published by | |
e5167999 | 11 | ;; the Free Software Foundation; either version 2, or (at your option) |
5cc564a6 | 12 | ;; any later version. |
13 | ||
14 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
15 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | ;; GNU General Public License for more details. | |
18 | ||
19 | ;; You should have received a copy of the GNU General Public License | |
b578f267 EN |
20 | ;; along with GNU Emacs; see the file COPYING. If not, write to the |
21 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
22 | ;; Boston, MA 02111-1307, USA. | |
5cc564a6 | 23 | |
c91c4e6d ER |
24 | ;;; Commentary: |
25 | ||
26 | ;; This package gives you the capability to run Emacs Lisp commands at | |
eb8c3be9 | 27 | ;; specified times in the future, either as one-shots or periodically. |
c91c4e6d | 28 | |
e5167999 ER |
29 | ;;; Code: |
30 | ||
4395bfdb | 31 | ;; Layout of a timer vector: |
9d690693 KH |
32 | ;; [triggered-p high-seconds low-seconds usecs repeat-delay |
33 | ;; function args idle-delay] | |
4395bfdb RS |
34 | |
35 | (defun timer-create () | |
36 | "Create a timer object." | |
9d690693 | 37 | (let ((timer (make-vector 8 nil))) |
c4ba2209 | 38 | (aset timer 0 t) |
4395bfdb RS |
39 | timer)) |
40 | ||
41 | (defun timerp (object) | |
42 | "Return t if OBJECT is a timer." | |
9d690693 | 43 | (and (vectorp object) (= (length object) 8))) |
4395bfdb RS |
44 | |
45 | (defun timer-set-time (timer time &optional delta) | |
46 | "Set the trigger time of TIMER to TIME. | |
cf9b15ce RS |
47 | TIME must be in the internal format returned by, e.g., `current-time'. |
48 | If optional third argument DELTA is a non-zero integer, make the timer | |
49 | fire repeatedly that many seconds apart." | |
4395bfdb RS |
50 | (or (timerp timer) |
51 | (error "Invalid timer")) | |
52 | (aset timer 1 (car time)) | |
53 | (aset timer 2 (if (consp (cdr time)) (car (cdr time)) (cdr time))) | |
1b966390 RS |
54 | (aset timer 3 (or (and (consp (cdr time)) (consp (cdr (cdr time))) |
55 | (nth 2 time)) | |
56 | 0)) | |
c4ba2209 | 57 | (aset timer 4 (and (numberp delta) (> delta 0) delta)) |
4395bfdb RS |
58 | timer) |
59 | ||
cf9b15ce RS |
60 | (defun timer-set-idle-time (timer secs &optional repeat) |
61 | "Set the trigger idle time of TIMER to SECS. | |
62 | If optional third argument REPEAT is non-nil, make the timer | |
63 | fire each time Emacs is idle for that many seconds." | |
64 | (or (timerp timer) | |
65 | (error "Invalid timer")) | |
66 | (aset timer 1 0) | |
67 | (aset timer 2 0) | |
68 | (aset timer 3 0) | |
69 | (timer-inc-time timer secs) | |
70 | (aset timer 4 repeat) | |
71 | timer) | |
72 | ||
c4ba2209 RS |
73 | (defun timer-relative-time (time secs &optional usecs) |
74 | "Advance TIME by SECS seconds and optionally USECS microseconds. | |
75 | SECS may be a fraction." | |
76 | (let ((high (car time)) | |
77 | (low (if (consp (cdr time)) (nth 1 time) (cdr time))) | |
78 | (micro (if (numberp (car-safe (cdr-safe (cdr time)))) | |
79 | (nth 2 time) | |
80 | 0))) | |
81 | ;; Add | |
82 | (if usecs (setq micro (+ micro usecs))) | |
83 | (if (floatp secs) | |
84 | (setq micro (+ micro (floor (* 1000000 (- secs (floor secs))))))) | |
85 | (setq low (+ low (floor secs))) | |
86 | ||
87 | ;; Normalize | |
88 | (setq low (+ low (/ micro 1000000))) | |
89 | (setq micro (mod micro 1000000)) | |
90 | (setq high (+ high (/ low 65536))) | |
91 | (setq low (logand low 65535)) | |
92 | ||
93 | (list high low (and (/= micro 0) micro)))) | |
4395bfdb RS |
94 | |
95 | (defun timer-inc-time (timer secs &optional usecs) | |
96 | "Increment the time set in TIMER by SECS seconds and USECS microseconds. | |
97 | SECS may be a fraction." | |
c4ba2209 RS |
98 | (let ((time (timer-relative-time |
99 | (list (aref timer 1) (aref timer 2) (aref timer 3)) | |
100 | secs | |
101 | usecs))) | |
102 | (aset timer 1 (nth 0 time)) | |
103 | (aset timer 2 (nth 1 time)) | |
104 | (aset timer 3 (or (nth 2 time) 0)))) | |
4395bfdb RS |
105 | |
106 | (defun timer-set-time-with-usecs (timer time usecs &optional delta) | |
107 | "Set the trigger time of TIMER to TIME. | |
cf9b15ce RS |
108 | TIME must be in the internal format returned by, e.g., `current-time'. |
109 | If optional third argument DELTA is a non-zero integer, make the timer | |
110 | fire repeatedly that many seconds apart." | |
4395bfdb RS |
111 | (or (timerp timer) |
112 | (error "Invalid timer")) | |
113 | (aset timer 1 (car time)) | |
114 | (aset timer 2 (if (consp (cdr time)) (car (cdr time)) (cdr time))) | |
115 | (aset timer 3 usecs) | |
c4ba2209 | 116 | (aset timer 4 (and (numberp delta) (> delta 0) delta)) |
4395bfdb RS |
117 | timer) |
118 | ||
119 | (defun timer-set-function (timer function &optional args) | |
120 | "Make TIMER call FUNCTION with optional ARGS when triggering." | |
121 | (or (timerp timer) | |
122 | (error "Invalid timer")) | |
123 | (aset timer 5 function) | |
124 | (aset timer 6 args) | |
125 | timer) | |
126 | \f | |
127 | (defun timer-activate (timer) | |
128 | "Put TIMER on the list of active timers." | |
129 | (if (and (timerp timer) | |
130 | (integerp (aref timer 1)) | |
131 | (integerp (aref timer 2)) | |
132 | (integerp (aref timer 3)) | |
133 | (aref timer 5)) | |
134 | (let ((timers timer-list) | |
135 | last) | |
136 | ;; Skip all timers to trigger before the new one. | |
137 | (while (and timers | |
138 | (or (> (aref timer 1) (aref (car timers) 1)) | |
139 | (and (= (aref timer 1) (aref (car timers) 1)) | |
140 | (> (aref timer 2) (aref (car timers) 2))) | |
141 | (and (= (aref timer 1) (aref (car timers) 1)) | |
142 | (= (aref timer 2) (aref (car timers) 2)) | |
143 | (> (aref timer 3) (aref (car timers) 3))))) | |
144 | (setq last timers | |
145 | timers (cdr timers))) | |
146 | ;; Insert new timer after last which possibly means in front of queue. | |
147 | (if last | |
148 | (setcdr last (cons timer timers)) | |
149 | (setq timer-list (cons timer timers))) | |
150 | (aset timer 0 nil) | |
9d690693 KH |
151 | (aset timer 7 nil) |
152 | nil) | |
153 | (error "Invalid or uninitialized timer"))) | |
154 | ||
155 | (defun timer-activate-when-idle (timer) | |
156 | "Arrange to activate TIMER whenever Emacs is next idle." | |
157 | (if (and (timerp timer) | |
158 | (integerp (aref timer 1)) | |
159 | (integerp (aref timer 2)) | |
160 | (integerp (aref timer 3)) | |
161 | (aref timer 5)) | |
162 | (let ((timers timer-idle-list) | |
163 | last) | |
164 | ;; Skip all timers to trigger before the new one. | |
165 | (while (and timers | |
166 | (or (> (aref timer 1) (aref (car timers) 1)) | |
167 | (and (= (aref timer 1) (aref (car timers) 1)) | |
168 | (> (aref timer 2) (aref (car timers) 2))) | |
169 | (and (= (aref timer 1) (aref (car timers) 1)) | |
170 | (= (aref timer 2) (aref (car timers) 2)) | |
171 | (> (aref timer 3) (aref (car timers) 3))))) | |
172 | (setq last timers | |
173 | timers (cdr timers))) | |
174 | ;; Insert new timer after last which possibly means in front of queue. | |
175 | (if last | |
176 | (setcdr last (cons timer timers)) | |
177 | (setq timer-idle-list (cons timer timers))) | |
178 | (aset timer 0 t) | |
179 | (aset timer 7 t) | |
4395bfdb RS |
180 | nil) |
181 | (error "Invalid or uninitialized timer"))) | |
182 | ||
c4ba2209 | 183 | (defalias 'disable-timeout 'cancel-timer) |
4395bfdb RS |
184 | (defun cancel-timer (timer) |
185 | "Remove TIMER from the list of active timers." | |
186 | (or (timerp timer) | |
187 | (error "Invalid timer")) | |
188 | (setq timer-list (delq timer timer-list)) | |
9d690693 | 189 | (setq timer-idle-list (delq timer timer-idle-list)) |
4395bfdb | 190 | nil) |
e2ec008d | 191 | |
4395bfdb RS |
192 | (defun cancel-function-timers (function) |
193 | "Cancel all timers scheduled by `run-at-time' which would run FUNCTION." | |
194 | (interactive "aCancel timers of function: ") | |
195 | (let ((tail timer-list)) | |
196 | (while tail | |
197 | (if (eq (aref (car tail) 5) function) | |
198 | (setq timer-list (delq (car tail) timer-list))) | |
9d690693 KH |
199 | (setq tail (cdr tail)))) |
200 | (let ((tail timer-idle-list)) | |
201 | (while tail | |
202 | (if (eq (aref (car tail) 5) function) | |
203 | (setq timer-idle-list (delq (car tail) timer-idle-list))) | |
4395bfdb RS |
204 | (setq tail (cdr tail))))) |
205 | \f | |
206 | ;; Set up the common handler for all timer events. Since the event has | |
207 | ;; the timer as parameter we can still distinguish. Note that using | |
208 | ;; special-event-map ensures that event timer events that arrive in the | |
209 | ;; middle of a key sequence being entered are still handled correctly. | |
210 | (define-key special-event-map [timer-event] 'timer-event-handler) | |
cf9b15ce | 211 | |
4395bfdb RS |
212 | (defun timer-event-handler (event) |
213 | "Call the handler for the timer in the event EVENT." | |
214 | (interactive "e") | |
c4ba2209 | 215 | (let ((timer (car-safe (cdr-safe event)))) |
4395bfdb RS |
216 | (if (timerp timer) |
217 | (progn | |
218 | ;; Delete from queue. | |
219 | (cancel-timer timer) | |
220 | ;; Run handler | |
1b966390 RS |
221 | (condition-case nil |
222 | (apply (aref timer 5) (aref timer 6)) | |
223 | (error nil)) | |
4395bfdb RS |
224 | ;; Re-schedule if requested. |
225 | (if (aref timer 4) | |
9d690693 KH |
226 | (if (aref timer 7) |
227 | (timer-activate-when-idle timer) | |
4395bfdb RS |
228 | (timer-inc-time timer (aref timer 4) 0) |
229 | (timer-activate timer)))) | |
230 | (error "Bogus timer event")))) | |
cf9b15ce RS |
231 | |
232 | ;; This function is incompatible with the one in levents.el. | |
233 | (defun timeout-event-p (event) | |
234 | "Non-nil if EVENT is a timeout event." | |
235 | (and (listp event) (eq (car event) 'timer-event))) | |
4395bfdb | 236 | \f |
49116ac0 | 237 | ;;;###autoload |
5cc564a6 | 238 | (defun run-at-time (time repeat function &rest args) |
cf9b15ce RS |
239 | "Perform an action after a delay of SECS seconds. |
240 | Repeat the action every REPEAT seconds, if REPEAT is non-nil. | |
241 | TIME should be a string like \"11:23pm\", nil meaning now, a number of seconds | |
242 | from now, or a value from `encode-time'. | |
243 | REPEAT may be an integer or floating point number. | |
244 | The action is to call FUNCTION with arguments ARGS. | |
c4ba2209 RS |
245 | |
246 | This function returns a timer object which you can use in `cancel-timer'." | |
5cc564a6 | 247 | (interactive "sRun at time: \nNRepeat interval: \naFunction: ") |
5cc564a6 | 248 | |
995b296f | 249 | ;; Special case: nil means "now" and is useful when repeating. |
c4ba2209 RS |
250 | (if (null time) |
251 | (setq time (current-time))) | |
252 | ||
0c6be60d RM |
253 | ;; Handle numbers as relative times in seconds. |
254 | (if (numberp time) | |
255 | (setq time (timer-relative-time (current-time) time))) | |
256 | ||
c4ba2209 RS |
257 | ;; Handle relative times like "2 hours and 35 minutes" |
258 | (if (stringp time) | |
259 | (let ((secs (timer-duration time))) | |
260 | (if secs | |
261 | (setq time (timer-relative-time (current-time) secs))))) | |
262 | ||
4395bfdb RS |
263 | ;; Handle "11:23pm" and the like. Interpret it as meaning today |
264 | ;; which admittedly is rather stupid if we have passed that time | |
cf9b15ce | 265 | ;; already. (Though only Emacs hackers hack Emacs at that time.) |
4395bfdb RS |
266 | (if (stringp time) |
267 | (progn | |
268 | (require 'diary-lib) | |
269 | (let ((hhmm (diary-entry-time time)) | |
270 | (now (decode-time))) | |
c4ba2209 RS |
271 | (if (>= hhmm 0) |
272 | (setq time | |
273 | (encode-time 0 (% hhmm 100) (/ hhmm 100) (nth 3 now) | |
274 | (nth 4 now) (nth 5 now) (nth 8 now))))))) | |
4395bfdb RS |
275 | |
276 | (or (consp time) | |
277 | (error "Invalid time format")) | |
278 | ||
279 | (or (null repeat) | |
280 | (natnump repeat) | |
281 | (error "Invalid repetition interval")) | |
282 | ||
283 | (let ((timer (timer-create))) | |
284 | (timer-set-time timer time repeat) | |
285 | (timer-set-function timer function args) | |
c4ba2209 RS |
286 | (timer-activate timer) |
287 | timer)) | |
4395bfdb | 288 | |
8a9fe4d2 | 289 | ;;;###autoload |
c4ba2209 | 290 | (defun run-with-timer (secs repeat function &rest args) |
8a9fe4d2 | 291 | "Perform an action after a delay of SECS seconds. |
4395bfdb | 292 | Repeat the action every REPEAT seconds, if REPEAT is non-nil. |
c4ba2209 RS |
293 | SECS and REPEAT may be integers or floating point numbers. |
294 | The action is to call FUNCTION with arguments ARGS. | |
295 | ||
296 | This function returns a timer object which you can use in `cancel-timer'." | |
4395bfdb | 297 | (interactive "sRun after delay (seconds): \nNRepeat interval: \naFunction: ") |
cf9b15ce | 298 | (apply 'run-at-time secs repeat function args)) |
4395bfdb | 299 | |
cf9b15ce RS |
300 | ;;;###autoload |
301 | (defun add-timeout (secs function object &optional repeat) | |
302 | "Add a timer to run SECS seconds from now, to call FUNCTION on OBJECT. | |
303 | If REPEAT is non-nil, repeat the timer every REPEAT seconds. | |
304 | This function is for compatibility; see also `run-with-timer'." | |
305 | (run-with-timer secs repeat function object)) | |
9d690693 KH |
306 | |
307 | ;;;###autoload | |
308 | (defun run-with-idle-timer (secs repeat function &rest args) | |
309 | "Perform an action the next time Emacs is idle for SECS seconds. | |
9d690693 KH |
310 | If REPEAT is non-nil, do this each time Emacs is idle for SECS seconds. |
311 | SECS may be an integer or a floating point number. | |
cf9b15ce | 312 | The action is to call FUNCTION with arguments ARGS. |
9d690693 KH |
313 | |
314 | This function returns a timer object which you can use in `cancel-timer'." | |
cf9b15ce RS |
315 | (interactive |
316 | (list (read-from-minibuffer "Run after idle (seconds): " nil nil t) | |
317 | (y-or-n-p "Repeat each time Emacs is idle? ") | |
318 | (intern (completing-read "Function: " obarray 'fboundp t)))) | |
9d690693 KH |
319 | (let ((timer (timer-create))) |
320 | (timer-set-function timer function args) | |
cf9b15ce | 321 | (timer-set-idle-time timer secs repeat) |
9d690693 KH |
322 | (timer-activate-when-idle timer) |
323 | timer)) | |
c4ba2209 | 324 | \f |
c4ba2209 RS |
325 | (defun with-timeout-handler (tag) |
326 | (throw tag 'timeout)) | |
327 | ||
328 | ;;;###autoload (put 'with-timeout 'lisp-indent-function 1) | |
329 | ||
330 | ;;;###autoload | |
331 | (defmacro with-timeout (list &rest body) | |
332 | "Run BODY, but if it doesn't finish in SECONDS seconds, give up. | |
333 | If we give up, we run the TIMEOUT-FORMS and return the value of the last one. | |
cf9b15ce RS |
334 | The call should look like: |
335 | (with-timeout (SECONDS TIMEOUT-FORMS...) BODY...) | |
c4ba2209 RS |
336 | The timeout is checked whenever Emacs waits for some kind of external |
337 | event \(such as keyboard input, input from subprocesses, or a certain time); | |
338 | if the program loops without waiting in any way, the timeout will not | |
339 | be detected." | |
340 | (let ((seconds (car list)) | |
341 | (timeout-forms (cdr list))) | |
342 | `(let ((with-timeout-tag (cons nil nil)) | |
343 | with-timeout-value with-timeout-timer) | |
344 | (if (catch with-timeout-tag | |
345 | (progn | |
346 | (setq with-timeout-timer | |
347 | (run-with-timer ,seconds nil | |
348 | 'with-timeout-handler | |
349 | with-timeout-tag)) | |
350 | (setq with-timeout-value (progn . ,body)) | |
351 | nil)) | |
352 | (progn . ,timeout-forms) | |
353 | (cancel-timer with-timeout-timer) | |
354 | with-timeout-value)))) | |
355 | ||
356 | (defun y-or-n-p-with-timeout (prompt seconds default-value) | |
357 | "Like (y-or-n-p PROMPT), with a timeout. | |
358 | If the user does not answer after SECONDS seconds, return DEFAULT-VALUE." | |
359 | (with-timeout (seconds default-value) | |
360 | (y-or-n-p prompt))) | |
361 | \f | |
362 | (defvar timer-duration-words | |
363 | (list (cons "microsec" 0.000001) | |
364 | (cons "microsecond" 0.000001) | |
365 | (cons "millisec" 0.001) | |
366 | (cons "millisecond" 0.001) | |
367 | (cons "sec" 1) | |
368 | (cons "second" 1) | |
369 | (cons "min" 60) | |
370 | (cons "minute" 60) | |
371 | (cons "hour" (* 60 60)) | |
372 | (cons "day" (* 24 60 60)) | |
373 | (cons "week" (* 7 24 60 60)) | |
374 | (cons "fortnight" (* 14 24 60 60)) | |
375 | (cons "month" (* 30 24 60 60)) ; Approximation | |
376 | (cons "year" (* 365.25 24 60 60)) ; Approximation | |
377 | ) | |
378 | "Alist mapping temporal words to durations in seconds") | |
379 | ||
380 | (defun timer-duration (string) | |
381 | "Return number of seconds specified by STRING, or nil if parsing fails." | |
382 | (let ((secs 0) | |
383 | (start 0) | |
384 | (case-fold-search t)) | |
385 | (while (string-match | |
386 | "[ \t]*\\([0-9.]+\\)?[ \t]*\\([a-z]+[a-rt-z]\\)s?[ \t]*" | |
387 | string start) | |
388 | (let ((count (if (match-beginning 1) | |
389 | (string-to-number (match-string 1 string)) | |
390 | 1)) | |
391 | (itemsize (cdr (assoc (match-string 2 string) | |
392 | timer-duration-words)))) | |
393 | (if itemsize | |
394 | (setq start (match-end 0) | |
395 | secs (+ secs (* count itemsize))) | |
396 | (setq secs nil | |
397 | start (length string))))) | |
1b966390 RS |
398 | (if (= start (length string)) |
399 | secs | |
400 | (if (string-match "\\`[0-9.]+\\'" string) | |
401 | (string-to-number string))))) | |
4395bfdb | 402 | \f |
c4ba2209 | 403 | (provide 'timer) |
4395bfdb | 404 | |
c4ba2209 | 405 | ;;; timer.el ends here |