Commit | Line | Data |
---|---|---|
4395bfdb | 1 | ;;; timers.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 ER |
28 | ;; The single entry point is `run-at-time'. |
29 | ||
e5167999 ER |
30 | ;;; Code: |
31 | ||
4395bfdb RS |
32 | ;; Layout of a timer vector: |
33 | ;; [triggered-p trigger-high trigger-low delta-secs function args] | |
34 | ||
35 | (defun timer-create () | |
36 | "Create a timer object." | |
37 | (let ((timer (make-vector 7 nil))) | |
38 | (aset timer 0 (make-vector 1 'timer-event)) | |
39 | timer)) | |
40 | ||
41 | (defun timerp (object) | |
42 | "Return t if OBJECT is a timer." | |
43 | (and (vectorp object) (= (length object) 7))) | |
44 | ||
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 menu seconds apart." | |
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))) | |
54 | (aset timer 3 (if (consp (cdr time)) (nth 2 time) 0)) | |
55 | (aset timer 4 (and (integerp delta) (> delta 0) delta)) | |
56 | timer) | |
57 | ||
58 | ||
59 | (defun timer-inc-time (timer secs &optional usecs) | |
60 | "Increment the time set in TIMER by SECS seconds and USECS microseconds. | |
61 | SECS may be a fraction." | |
62 | (or usecs (setq usecs 0)) | |
63 | (if (floatp secs) | |
64 | (let* ((integer (floor secs)) | |
65 | (fraction (floor (* 1000000 (- secs integer))))) | |
66 | (setq usecs fraction secs integer))) | |
67 | (let ((newusecs (+ (aref timer 3) usecs))) | |
68 | (aset timer 3 (mod newusecs 1000000)) | |
69 | (setq secs (+ secs (/ newusecs 1000000)))) | |
70 | (let ((newlow (+ (aref timer 2) secs)) | |
71 | (newhigh (aref timer 1))) | |
72 | (setq newhigh (+ newhigh (/ newlow 65536)) | |
73 | newlow (logand newlow 65535)) | |
74 | (aset timer 1 newhigh) | |
75 | (aset timer 2 newlow))) | |
76 | ||
77 | (defun timer-set-time-with-usecs (timer time usecs &optional delta) | |
78 | "Set the trigger time of TIMER to TIME. | |
79 | TIME must be in the internal format returned by, e.g., `current-time' | |
80 | If optional third argument DELTA is a non-zero integer make the timer | |
81 | fire repeatedly that menu seconds apart." | |
82 | (or (timerp timer) | |
83 | (error "Invalid timer")) | |
84 | (aset timer 1 (car time)) | |
85 | (aset timer 2 (if (consp (cdr time)) (car (cdr time)) (cdr time))) | |
86 | (aset timer 3 usecs) | |
87 | (aset timer 4 (and (integerp delta) (> delta 0) delta)) | |
88 | timer) | |
89 | ||
90 | (defun timer-set-function (timer function &optional args) | |
91 | "Make TIMER call FUNCTION with optional ARGS when triggering." | |
92 | (or (timerp timer) | |
93 | (error "Invalid timer")) | |
94 | (aset timer 5 function) | |
95 | (aset timer 6 args) | |
96 | timer) | |
97 | \f | |
98 | (defun timer-activate (timer) | |
99 | "Put TIMER on the list of active timers." | |
100 | (if (and (timerp timer) | |
101 | (integerp (aref timer 1)) | |
102 | (integerp (aref timer 2)) | |
103 | (integerp (aref timer 3)) | |
104 | (aref timer 5)) | |
105 | (let ((timers timer-list) | |
106 | last) | |
107 | ;; Skip all timers to trigger before the new one. | |
108 | (while (and timers | |
109 | (or (> (aref timer 1) (aref (car timers) 1)) | |
110 | (and (= (aref timer 1) (aref (car timers) 1)) | |
111 | (> (aref timer 2) (aref (car timers) 2))) | |
112 | (and (= (aref timer 1) (aref (car timers) 1)) | |
113 | (= (aref timer 2) (aref (car timers) 2)) | |
114 | (> (aref timer 3) (aref (car timers) 3))))) | |
115 | (setq last timers | |
116 | timers (cdr timers))) | |
117 | ;; Insert new timer after last which possibly means in front of queue. | |
118 | (if last | |
119 | (setcdr last (cons timer timers)) | |
120 | (setq timer-list (cons timer timers))) | |
121 | (aset timer 0 nil) | |
122 | nil) | |
123 | (error "Invalid or uninitialized timer"))) | |
124 | ||
125 | (defun cancel-timer (timer) | |
126 | "Remove TIMER from the list of active timers." | |
127 | (or (timerp timer) | |
128 | (error "Invalid timer")) | |
129 | (setq timer-list (delq timer timer-list)) | |
130 | nil) | |
e2ec008d | 131 | |
4395bfdb RS |
132 | (defun cancel-function-timers (function) |
133 | "Cancel all timers scheduled by `run-at-time' which would run FUNCTION." | |
134 | (interactive "aCancel timers of function: ") | |
135 | (let ((tail timer-list)) | |
136 | (while tail | |
137 | (if (eq (aref (car tail) 5) function) | |
138 | (setq timer-list (delq (car tail) timer-list))) | |
139 | (setq tail (cdr tail))))) | |
140 | \f | |
141 | ;; Set up the common handler for all timer events. Since the event has | |
142 | ;; the timer as parameter we can still distinguish. Note that using | |
143 | ;; special-event-map ensures that event timer events that arrive in the | |
144 | ;; middle of a key sequence being entered are still handled correctly. | |
145 | (define-key special-event-map [timer-event] 'timer-event-handler) | |
146 | (defun timer-event-handler (event) | |
147 | "Call the handler for the timer in the event EVENT." | |
148 | (interactive "e") | |
149 | (let ((timer (cdr-safe event))) | |
150 | (if (timerp timer) | |
151 | (progn | |
152 | ;; Delete from queue. | |
153 | (cancel-timer timer) | |
154 | ;; Run handler | |
155 | (apply (aref timer 5) (aref timer 6)) | |
156 | ;; Re-schedule if requested. | |
157 | (if (aref timer 4) | |
158 | (progn | |
159 | (timer-inc-time timer (aref timer 4) 0) | |
160 | (timer-activate timer)))) | |
161 | (error "Bogus timer event")))) | |
162 | \f | |
49116ac0 | 163 | ;;;###autoload |
5cc564a6 | 164 | (defun run-at-time (time repeat function &rest args) |
165 | "Run a function at a time, and optionally on a regular interval. | |
166 | Arguments are TIME, REPEAT, FUNCTION &rest ARGS. | |
4395bfdb | 167 | TIME is a string like \"11:23pm\" or a value from `encode-time'. |
5cc564a6 | 168 | REPEAT, an integer number of seconds, is the interval on which to repeat |
4395bfdb | 169 | the call to the function. If REPEAT is nil or 0, call it just once." |
5cc564a6 | 170 | (interactive "sRun at time: \nNRepeat interval: \naFunction: ") |
5cc564a6 | 171 | |
4395bfdb RS |
172 | ;; Handle "11:23pm" and the like. Interpret it as meaning today |
173 | ;; which admittedly is rather stupid if we have passed that time | |
174 | ;; already. Unfortunately we don't have a `parse-time' function | |
175 | ;; to do the right thing. | |
176 | (if (stringp time) | |
177 | (progn | |
178 | (require 'diary-lib) | |
179 | (let ((hhmm (diary-entry-time time)) | |
180 | (now (decode-time))) | |
181 | (if (< hhmm 0) | |
182 | (setq time 'bad) | |
183 | (setq time | |
184 | (encode-time 0 (% hhmm 100) (/ hhmm 100) (nth 3 now) | |
185 | (nth 4 now) (nth 5 now) (nth 8 now))))))) | |
186 | ||
187 | ;; Special case: nil means "now" and is useful when repeting. | |
188 | (if (null time) | |
189 | (setq time (current-time))) | |
190 | ||
191 | (or (consp time) | |
192 | (error "Invalid time format")) | |
193 | ||
194 | (or (null repeat) | |
195 | (natnump repeat) | |
196 | (error "Invalid repetition interval")) | |
197 | ||
198 | (let ((timer (timer-create))) | |
199 | (timer-set-time timer time repeat) | |
200 | (timer-set-function timer function args) | |
201 | (timer-activate timer))) | |
202 | ||
8a9fe4d2 RS |
203 | ;;;###autoload |
204 | (defun run-after-delay (secs repeat function &rest args) | |
205 | "Perform an action after a delay of SECS seconds. | |
4395bfdb | 206 | Repeat the action every REPEAT seconds, if REPEAT is non-nil. |
8a9fe4d2 | 207 | SECS and REPEAT need not be integers. |
4395bfdb RS |
208 | The action is to call FUNCTION with arguments ARGS." |
209 | (interactive "sRun after delay (seconds): \nNRepeat interval: \naFunction: ") | |
210 | ||
211 | (or (null repeat) | |
8a9fe4d2 | 212 | (and (numberp repeat) (>= repeat 0)) |
4395bfdb RS |
213 | (error "Invalid repetition interval")) |
214 | ||
215 | (let ((timer (timer-create))) | |
216 | (timer-set-time timer (current-time)) | |
8a9fe4d2 | 217 | (timer-inc-time timer secs) |
4395bfdb RS |
218 | (timer-set-function timer function args) |
219 | (timer-activate timer))) | |
220 | \f | |
221 | (provide 'timers) | |
222 | ||
223 | ;;; timers.el ends here |