Debian Codegraph @

closure-library/closure/goog/timer/timer.js

raw
1 // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview A timer class to which other classes and objects can listen on.
17 * This is only an abstraction above {@code setInterval}.
18 *
19 * @see ../demos/timers.html
20 */
21
22 goog.provide('goog.Timer');
23
24 goog.require('goog.Promise');
25 goog.require('goog.events.EventTarget');
26
27
28
29 /**
30 * Class for handling timing events.
31 *
32 * @param {number=} opt_interval Number of ms between ticks (default: 1ms).
33 * @param {Object=} opt_timerObject An object that has {@code setTimeout},
34 * {@code setInterval}, {@code clearTimeout} and {@code clearInterval}
35 * (e.g., {@code window}).
36 * @constructor
37 * @extends {goog.events.EventTarget}
38 */
39 goog.Timer = function(opt_interval, opt_timerObject) {
40 goog.events.EventTarget.call(this);
41
42 /**
43 * Number of ms between ticks
44 * @private {number}
45 */
46 this.interval_ = opt_interval || 1;
47
48 /**
49 * An object that implements {@code setTimeout}, {@code setInterval},
50 * {@code clearTimeout} and {@code clearInterval}. We default to the window
51 * object. Changing this on {@link goog.Timer.prototype} changes the object
52 * for all timer instances which can be useful if your environment has some
53 * other implementation of timers than the {@code window} object.
54 * @private {{setTimeout:!Function, clearTimeout:!Function}}
55 */
56 this.timerObject_ = /** @type {{setTimeout, clearTimeout}} */ (
57 opt_timerObject || goog.Timer.defaultTimerObject);
58
59 /**
60 * Cached {@code tick_} bound to the object for later use in the timer.
61 * @private {Function}
62 * @const
63 */
64 this.boundTick_ = goog.bind(this.tick_, this);
65
66 /**
67 * Firefox browser often fires the timer event sooner (sometimes MUCH sooner)
68 * than the requested timeout. So we compare the time to when the event was
69 * last fired, and reschedule if appropriate. See also
70 * {@link goog.Timer.intervalScale}.
71 * @private {number}
72 */
73 this.last_ = goog.now();
74 };
75 goog.inherits(goog.Timer, goog.events.EventTarget);
76
77
78 /**
79 * Maximum timeout value.
80 *
81 * Timeout values too big to fit into a signed 32-bit integer may cause overflow
82 * in FF, Safari, and Chrome, resulting in the timeout being scheduled
83 * immediately. It makes more sense simply not to schedule these timeouts, since
84 * 24.8 days is beyond a reasonable expectation for the browser to stay open.
85 *
86 * @private {number}
87 * @const
88 */
89 goog.Timer.MAX_TIMEOUT_ = 2147483647;
90
91
92 /**
93 * A timer ID that cannot be returned by any known implementation of
94 * {@code window.setTimeout}. Passing this value to {@code window.clearTimeout}
95 * should therefore be a no-op.
96 *
97 * @private {number}
98 * @const
99 */
100 goog.Timer.INVALID_TIMEOUT_ID_ = -1;
101
102
103 /**
104 * Whether this timer is enabled
105 * @type {boolean}
106 */
107 goog.Timer.prototype.enabled = false;
108
109
110 /**
111 * An object that implements {@code setTimeout}, {@code setInterval},
112 * {@code clearTimeout} and {@code clearInterval}. We default to the global
113 * object. Changing {@code goog.Timer.defaultTimerObject} changes the object for
114 * all timer instances which can be useful if your environment has some other
115 * implementation of timers you'd like to use.
116 * @type {{setTimeout, clearTimeout}}
117 */
118 goog.Timer.defaultTimerObject = goog.global;
119
120
121 /**
122 * Variable that controls the timer error correction. If the timer is called
123 * before the requested interval times {@code intervalScale}, which often
124 * happens on Mozilla, the timer is rescheduled.
125 * @see {@link #last_}
126 * @type {number}
127 */
128 goog.Timer.intervalScale = 0.8;
129
130
131 /**
132 * Variable for storing the result of {@code setInterval}.
133 * @private {?number}
134 */
135 goog.Timer.prototype.timer_ = null;
136
137
138 /**
139 * Gets the interval of the timer.
140 * @return {number} interval Number of ms between ticks.
141 */
142 goog.Timer.prototype.getInterval = function() {
143 return this.interval_;
144 };
145
146
147 /**
148 * Sets the interval of the timer.
149 * @param {number} interval Number of ms between ticks.
150 */
151 goog.Timer.prototype.setInterval = function(interval) {
152 this.interval_ = interval;
153 if (this.timer_ && this.enabled) {
154 // Stop and then start the timer to reset the interval.
155 this.stop();
156 this.start();
157 } else if (this.timer_) {
158 this.stop();
159 }
160 };
161
162
163 /**
164 * Callback for the {@code setTimeout} used by the timer.
165 * @private
166 */
167 goog.Timer.prototype.tick_ = function() {
168 if (this.enabled) {
169 var elapsed = goog.now() - this.last_;
170 if (elapsed > 0 && elapsed < this.interval_ * goog.Timer.intervalScale) {
171 this.timer_ = this.timerObject_.setTimeout(
172 this.boundTick_, this.interval_ - elapsed);
173 return;
174 }
175
176 // Prevents setInterval from registering a duplicate timeout when called
177 // in the timer event handler.
178 if (this.timer_) {
179 this.timerObject_.clearTimeout(this.timer_);
180 this.timer_ = null;
181 }
182
183 this.dispatchTick();
184 // The timer could be stopped in the timer event handler.
185 if (this.enabled) {
186 this.timer_ =
187 this.timerObject_.setTimeout(this.boundTick_, this.interval_);
188 this.last_ = goog.now();
189 }
190 }
191 };
192
193
194 /**
195 * Dispatches the TICK event. This is its own method so subclasses can override.
196 */
197 goog.Timer.prototype.dispatchTick = function() {
198 this.dispatchEvent(goog.Timer.TICK);
199 };
200
201
202 /**
203 * Starts the timer.
204 */
205 goog.Timer.prototype.start = function() {
206 this.enabled = true;
207
208 // If there is no interval already registered, start it now
209 if (!this.timer_) {
210 // IMPORTANT!
211 // window.setInterval in FireFox has a bug - it fires based on
212 // absolute time, rather than on relative time. What this means
213 // is that if a computer is sleeping/hibernating for 24 hours
214 // and the timer interval was configured to fire every 1000ms,
215 // then after the PC wakes up the timer will fire, in rapid
216 // succession, 3600*24 times.
217 // This bug is described here and is already fixed, but it will
218 // take time to propagate, so for now I am switching this over
219 // to setTimeout logic.
220 // https://bugzilla.mozilla.org/show_bug.cgi?id=376643
221 //
222 this.timer_ = this.timerObject_.setTimeout(this.boundTick_, this.interval_);
223 this.last_ = goog.now();
224 }
225 };
226
227
228 /**
229 * Stops the timer.
230 */
231 goog.Timer.prototype.stop = function() {
232 this.enabled = false;
233 if (this.timer_) {
234 this.timerObject_.clearTimeout(this.timer_);
235 this.timer_ = null;
236 }
237 };
238
239
240 /** @override */
241 goog.Timer.prototype.disposeInternal = function() {
242 goog.Timer.superClass_.disposeInternal.call(this);
243 this.stop();
244 delete this.timerObject_;
245 };
246
247
248 /**
249 * Constant for the timer's event type.
250 * @const
251 */
252 goog.Timer.TICK = 'tick';
253
254
255 /**
256 * Calls the given function once, after the optional pause.
257 * <p>
258 * The function is always called asynchronously, even if the delay is 0. This
259 * is a common trick to schedule a function to run after a batch of browser
260 * event processing.
261 *
262 * @param {function(this:SCOPE)|{handleEvent:function()}|null} listener Function
263 * or object that has a handleEvent method.
264 * @param {number=} opt_delay Milliseconds to wait; default is 0.
265 * @param {SCOPE=} opt_handler Object in whose scope to call the listener.
266 * @return {number} A handle to the timer ID.
267 * @template SCOPE
268 */
269 goog.Timer.callOnce = function(listener, opt_delay, opt_handler) {
270 if (goog.isFunction(listener)) {
271 if (opt_handler) {
272 listener = goog.bind(listener, opt_handler);
273 }
274 } else if (listener && typeof listener.handleEvent == 'function') {
275 // using typeof to prevent strict js warning
276 listener = goog.bind(listener.handleEvent, listener);
277 } else {
278 throw new Error('Invalid listener argument');
279 }
280
281 if (Number(opt_delay) > goog.Timer.MAX_TIMEOUT_) {
282 // Timeouts greater than MAX_INT return immediately due to integer
283 // overflow in many browsers. Since MAX_INT is 24.8 days, just don't
284 // schedule anything at all.
285 return goog.Timer.INVALID_TIMEOUT_ID_;
286 } else {
287 return goog.Timer.defaultTimerObject.setTimeout(listener, opt_delay || 0);
288 }
289 };
290
291
292 /**
293 * Clears a timeout initiated by {@link #callOnce}.
294 * @param {?number} timerId A timer ID.
295 */
296 goog.Timer.clear = function(timerId) {
297 goog.Timer.defaultTimerObject.clearTimeout(timerId);
298 };
299
300
301 /**
302 * @param {number} delay Milliseconds to wait.
303 * @param {(RESULT|goog.Thenable<RESULT>|Thenable)=} opt_result The value
304 * with which the promise will be resolved.
305 * @return {!goog.Promise<RESULT>} A promise that will be resolved after
306 * the specified delay, unless it is canceled first.
307 * @template RESULT
308 */
309 goog.Timer.promise = function(delay, opt_result) {
310 var timerKey = null;
311 return new goog
312 .Promise(function(resolve, reject) {
313 timerKey =
314 goog.Timer.callOnce(function() { resolve(opt_result); }, delay);
315 if (timerKey == goog.Timer.INVALID_TIMEOUT_ID_) {
316 reject(new Error('Failed to schedule timer.'));
317 }
318 })
319 .thenCatch(function(error) {
320 // Clear the timer. The most likely reason is "cancel" signal.
321 goog.Timer.clear(timerKey);
322 throw error;
323 });
324 };