1 ;;; timer.el --- run a function with args at some time in future.
3 ;; Copyright (C) 1996 Free Software Foundation, Inc.
7 ;; This file is part of GNU Emacs.
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
11 ;; the Free Software Foundation; either version 2, or (at your option)
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.
19 ;; You should have received a copy of the GNU General Public License
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.
26 ;; This package gives you the capability to run Emacs Lisp commands at
27 ;; specified times in the future, either as one-shots or periodically.
31 ;; Layout of a timer vector:
32 ;; [triggered-p high-seconds low-seconds usecs repeat-delay
33 ;; function args idle-delay]
35 (defun timer-create ()
36 "Create a timer object."
37 (let ((timer (make-vector 8 nil
)))
41 (defun timerp (object)
42 "Return t if OBJECT is a timer."
43 (and (vectorp object
) (= (length object
) 8)))
45 (defun timer-set-time (timer time
&optional delta
)
46 "Set the trigger time of TIMER to TIME.
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."
51 (error "Invalid timer"))
52 (aset timer
1 (car time
))
53 (aset timer
2 (if (consp (cdr time
)) (car (cdr time
)) (cdr time
)))
54 (aset timer
3 (if (consp (cdr time
)) (nth 2 time
) 0))
55 (aset timer
4 (and (numberp delta
) (> delta
0) delta
))
58 (defun timer-set-idle-time (timer secs
&optional repeat
)
59 "Set the trigger idle time of TIMER to SECS.
60 If optional third argument REPEAT is non-nil, make the timer
61 fire each time Emacs is idle for that many seconds."
63 (error "Invalid timer"))
67 (timer-inc-time timer secs
)
71 (defun timer-relative-time (time secs
&optional usecs
)
72 "Advance TIME by SECS seconds and optionally USECS microseconds.
73 SECS may be a fraction."
74 (let ((high (car time
))
75 (low (if (consp (cdr time
)) (nth 1 time
) (cdr time
)))
76 (micro (if (numberp (car-safe (cdr-safe (cdr time
))))
80 (if usecs
(setq micro
(+ micro usecs
)))
82 (setq micro
(+ micro
(floor (* 1000000 (- secs
(floor secs
)))))))
83 (setq low
(+ low
(floor secs
)))
86 (setq low
(+ low
(/ micro
1000000)))
87 (setq micro
(mod micro
1000000))
88 (setq high
(+ high
(/ low
65536)))
89 (setq low
(logand low
65535))
91 (list high low
(and (/= micro
0) micro
))))
93 (defun timer-inc-time (timer secs
&optional usecs
)
94 "Increment the time set in TIMER by SECS seconds and USECS microseconds.
95 SECS may be a fraction."
96 (let ((time (timer-relative-time
97 (list (aref timer
1) (aref timer
2) (aref timer
3))
100 (aset timer
1 (nth 0 time
))
101 (aset timer
2 (nth 1 time
))
102 (aset timer
3 (or (nth 2 time
) 0))))
104 (defun timer-set-time-with-usecs (timer time usecs
&optional delta
)
105 "Set the trigger time of TIMER to TIME.
106 TIME must be in the internal format returned by, e.g., `current-time'.
107 If optional third argument DELTA is a non-zero integer, make the timer
108 fire repeatedly that many seconds apart."
110 (error "Invalid timer"))
111 (aset timer
1 (car time
))
112 (aset timer
2 (if (consp (cdr time
)) (car (cdr time
)) (cdr time
)))
114 (aset timer
4 (and (numberp delta
) (> delta
0) delta
))
117 (defun timer-set-function (timer function
&optional args
)
118 "Make TIMER call FUNCTION with optional ARGS when triggering."
120 (error "Invalid timer"))
121 (aset timer
5 function
)
125 (defun timer-activate (timer)
126 "Put TIMER on the list of active timers."
127 (if (and (timerp timer
)
128 (integerp (aref timer
1))
129 (integerp (aref timer
2))
130 (integerp (aref timer
3))
132 (let ((timers timer-list
)
134 ;; Skip all timers to trigger before the new one.
136 (or (> (aref timer
1) (aref (car timers
) 1))
137 (and (= (aref timer
1) (aref (car timers
) 1))
138 (> (aref timer
2) (aref (car timers
) 2)))
139 (and (= (aref timer
1) (aref (car timers
) 1))
140 (= (aref timer
2) (aref (car timers
) 2))
141 (> (aref timer
3) (aref (car timers
) 3)))))
143 timers
(cdr timers
)))
144 ;; Insert new timer after last which possibly means in front of queue.
146 (setcdr last
(cons timer timers
))
147 (setq timer-list
(cons timer timers
)))
151 (error "Invalid or uninitialized timer")))
153 (defun timer-activate-when-idle (timer)
154 "Arrange to activate TIMER whenever Emacs is next idle."
155 (if (and (timerp timer
)
156 (integerp (aref timer
1))
157 (integerp (aref timer
2))
158 (integerp (aref timer
3))
160 (let ((timers timer-idle-list
)
162 ;; Skip all timers to trigger before the new one.
164 (or (> (aref timer
1) (aref (car timers
) 1))
165 (and (= (aref timer
1) (aref (car timers
) 1))
166 (> (aref timer
2) (aref (car timers
) 2)))
167 (and (= (aref timer
1) (aref (car timers
) 1))
168 (= (aref timer
2) (aref (car timers
) 2))
169 (> (aref timer
3) (aref (car timers
) 3)))))
171 timers
(cdr timers
)))
172 ;; Insert new timer after last which possibly means in front of queue.
174 (setcdr last
(cons timer timers
))
175 (setq timer-idle-list
(cons timer timers
)))
179 (error "Invalid or uninitialized timer")))
181 (defalias 'disable-timeout
'cancel-timer
)
182 (defun cancel-timer (timer)
183 "Remove TIMER from the list of active timers."
185 (error "Invalid timer"))
186 (setq timer-list
(delq timer timer-list
))
187 (setq timer-idle-list
(delq timer timer-idle-list
))
190 (defun cancel-function-timers (function)
191 "Cancel all timers scheduled by `run-at-time' which would run FUNCTION."
192 (interactive "aCancel timers of function: ")
193 (let ((tail timer-list
))
195 (if (eq (aref (car tail
) 5) function
)
196 (setq timer-list
(delq (car tail
) timer-list
)))
197 (setq tail
(cdr tail
))))
198 (let ((tail timer-idle-list
))
200 (if (eq (aref (car tail
) 5) function
)
201 (setq timer-idle-list
(delq (car tail
) timer-idle-list
)))
202 (setq tail
(cdr tail
)))))
204 ;; Set up the common handler for all timer events. Since the event has
205 ;; the timer as parameter we can still distinguish. Note that using
206 ;; special-event-map ensures that event timer events that arrive in the
207 ;; middle of a key sequence being entered are still handled correctly.
208 (define-key special-event-map
[timer-event
] 'timer-event-handler
)
210 (defun timer-event-handler (event)
211 "Call the handler for the timer in the event EVENT."
213 (let ((timer (car-safe (cdr-safe event
))))
216 ;; Delete from queue.
219 (apply (aref timer
5) (aref timer
6))
220 ;; Re-schedule if requested.
223 (timer-activate-when-idle timer
)
224 (timer-inc-time timer
(aref timer
4) 0)
225 (timer-activate timer
))))
226 (error "Bogus timer event"))))
228 ;; This function is incompatible with the one in levents.el.
229 (defun timeout-event-p (event)
230 "Non-nil if EVENT is a timeout event."
231 (and (listp event
) (eq (car event
) 'timer-event
)))
234 (defun run-at-time (time repeat function
&rest args
)
235 "Perform an action after a delay of SECS seconds.
236 Repeat the action every REPEAT seconds, if REPEAT is non-nil.
237 TIME should be a string like \"11:23pm\", nil meaning now, a number of seconds
238 from now, or a value from `encode-time'.
239 REPEAT may be an integer or floating point number.
240 The action is to call FUNCTION with arguments ARGS.
242 This function returns a timer object which you can use in `cancel-timer'."
243 (interactive "sRun at time: \nNRepeat interval: \naFunction: ")
245 ;; Special case: nil means "now" and is useful when repeating.
247 (setq time
(current-time)))
249 ;; Handle numbers as relative times in seconds.
251 (setq time
(timer-relative-time (current-time) time
)))
253 ;; Handle relative times like "2 hours and 35 minutes"
255 (let ((secs (timer-duration time
)))
257 (setq time
(timer-relative-time (current-time) secs
)))))
259 ;; Handle "11:23pm" and the like. Interpret it as meaning today
260 ;; which admittedly is rather stupid if we have passed that time
261 ;; already. (Though only Emacs hackers hack Emacs at that time.)
265 (let ((hhmm (diary-entry-time time
))
269 (encode-time 0 (% hhmm
100) (/ hhmm
100) (nth 3 now
)
270 (nth 4 now
) (nth 5 now
) (nth 8 now
)))))))
273 (error "Invalid time format"))
277 (error "Invalid repetition interval"))
279 (let ((timer (timer-create)))
280 (timer-set-time timer time repeat
)
281 (timer-set-function timer function args
)
282 (timer-activate timer
)
286 (defun run-with-timer (secs repeat function
&rest args
)
287 "Perform an action after a delay of SECS seconds.
288 Repeat the action every REPEAT seconds, if REPEAT is non-nil.
289 SECS and REPEAT may be integers or floating point numbers.
290 The action is to call FUNCTION with arguments ARGS.
292 This function returns a timer object which you can use in `cancel-timer'."
293 (interactive "sRun after delay (seconds): \nNRepeat interval: \naFunction: ")
294 (apply 'run-at-time secs repeat function args
))
297 (defun add-timeout (secs function object
&optional repeat
)
298 "Add a timer to run SECS seconds from now, to call FUNCTION on OBJECT.
299 If REPEAT is non-nil, repeat the timer every REPEAT seconds.
300 This function is for compatibility; see also `run-with-timer'."
301 (run-with-timer secs repeat function object
))
304 (defun run-with-idle-timer (secs repeat function
&rest args
)
305 "Perform an action the next time Emacs is idle for SECS seconds.
306 If REPEAT is non-nil, do this each time Emacs is idle for SECS seconds.
307 SECS may be an integer or a floating point number.
308 The action is to call FUNCTION with arguments ARGS.
310 This function returns a timer object which you can use in `cancel-timer'."
312 (list (read-from-minibuffer "Run after idle (seconds): " nil nil t
)
313 (y-or-n-p "Repeat each time Emacs is idle? ")
314 (intern (completing-read "Function: " obarray
'fboundp t
))))
315 (let ((timer (timer-create)))
316 (timer-set-function timer function args
)
317 (timer-set-idle-time timer secs repeat
)
318 (timer-activate-when-idle timer
)
321 (defun with-timeout-handler (tag)
322 (throw tag
'timeout
))
324 ;;;###autoload (put 'with-timeout 'lisp-indent-function 1)
327 (defmacro with-timeout
(list &rest body
)
328 "Run BODY, but if it doesn't finish in SECONDS seconds, give up.
329 If we give up, we run the TIMEOUT-FORMS and return the value of the last one.
330 The call should look like:
331 (with-timeout (SECONDS TIMEOUT-FORMS...) BODY...)
332 The timeout is checked whenever Emacs waits for some kind of external
333 event \(such as keyboard input, input from subprocesses, or a certain time);
334 if the program loops without waiting in any way, the timeout will not
336 (let ((seconds (car list
))
337 (timeout-forms (cdr list
)))
338 `(let ((with-timeout-tag (cons nil nil
))
339 with-timeout-value with-timeout-timer
)
340 (if (catch with-timeout-tag
342 (setq with-timeout-timer
343 (run-with-timer ,seconds nil
344 'with-timeout-handler
346 (setq with-timeout-value
(progn .
,body
))
348 (progn .
,timeout-forms
)
349 (cancel-timer with-timeout-timer
)
350 with-timeout-value
))))
352 (defun y-or-n-p-with-timeout (prompt seconds default-value
)
353 "Like (y-or-n-p PROMPT), with a timeout.
354 If the user does not answer after SECONDS seconds, return DEFAULT-VALUE."
355 (with-timeout (seconds default-value
)
358 (defvar timer-duration-words
359 (list (cons "microsec" 0.000001)
360 (cons "microsecond" 0.000001)
361 (cons "millisec" 0.001)
362 (cons "millisecond" 0.001)
367 (cons "hour" (* 60 60))
368 (cons "day" (* 24 60 60))
369 (cons "week" (* 7 24 60 60))
370 (cons "fortnight" (* 14 24 60 60))
371 (cons "month" (* 30 24 60 60)) ; Approximation
372 (cons "year" (* 365.25 24 60 60)) ; Approximation
374 "Alist mapping temporal words to durations in seconds")
376 (defun timer-duration (string)
377 "Return number of seconds specified by STRING, or nil if parsing fails."
380 (case-fold-search t
))
382 "[ \t]*\\([0-9.]+\\)?[ \t]*\\([a-z]+[a-rt-z]\\)s?[ \t]*"
384 (let ((count (if (match-beginning 1)
385 (string-to-number (match-string 1 string
))
387 (itemsize (cdr (assoc (match-string 2 string
)
388 timer-duration-words
))))
390 (setq start
(match-end 0)
391 secs
(+ secs
(* count itemsize
)))
393 start
(length string
)))))
398 ;;; timer.el ends here