Debian Codegraph @

closure-library/closure/goog/async/debouncer.js

raw
1 // Copyright 2015 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 Definition of the goog.async.Debouncer class.
17 *
18 * @see ../demos/timers.html
19 */
20
21 goog.provide('goog.async.Debouncer');
22
23 goog.require('goog.Disposable');
24 goog.require('goog.Timer');
25
26
27
28 /**
29 * Debouncer will perform a specified action exactly once for any sequence of
30 * signals fired repeatedly so long as they are fired less than a specified
31 * interval apart (in milliseconds). Whether it receives one signal or multiple,
32 * it will always wait until a full interval has elapsed since the last signal
33 * before performing the action.
34 * @param {function(this: T, ...?)} listener Function to callback when the
35 * action is triggered.
36 * @param {number} interval Interval over which to debounce. The listener will
37 * only be called after the full interval has elapsed since the last signal.
38 * @param {T=} opt_handler Object in whose scope to call the listener.
39 * @constructor
40 * @struct
41 * @extends {goog.Disposable}
42 * @final
43 * @template T
44 */
45 goog.async.Debouncer = function(listener, interval, opt_handler) {
46 goog.async.Debouncer.base(this, 'constructor');
47
48 /**
49 * Function to callback
50 * @const @private {function(this: T, ...?)}
51 */
52 this.listener_ =
53 opt_handler != null ? goog.bind(listener, opt_handler) : listener;
54
55 /**
56 * Interval for the debounce time
57 * @const @private {number}
58 */
59 this.interval_ = interval;
60
61 /**
62 * Cached callback function invoked after the debounce timeout completes
63 * @const @private {!Function}
64 */
65 this.callback_ = goog.bind(this.onTimer_, this);
66
67 /**
68 * Indicates that the action is pending and needs to be fired.
69 * @private {boolean}
70 */
71 this.shouldFire_ = false;
72
73 /**
74 * Indicates the count of nested pauses currently in effect on the debouncer.
75 * When this count is not zero, fired actions will be postponed until the
76 * debouncer is resumed enough times to drop the pause count to zero.
77 * @private {number}
78 */
79 this.pauseCount_ = 0;
80
81 /**
82 * Timer for scheduling the next callback
83 * @private {?number}
84 */
85 this.timer_ = null;
86
87 /**
88 * When set this is a timestamp. On the onfire we want to reschedule the
89 * callback so it ends up at this time.
90 * @private {?number}
91 */
92 this.refireAt_ = null;
93
94 /**
95 * The last arguments passed into {@code fire}.
96 * @private {!IArrayLike}
97 */
98 this.args_ = [];
99 };
100 goog.inherits(goog.async.Debouncer, goog.Disposable);
101
102
103 /**
104 * Notifies the debouncer that the action has happened. It will debounce the
105 * call so that the callback is only called after the last action in a sequence
106 * of actions separated by periods less the interval parameter passed to the
107 * constructor, passing the arguments from the last call of this function into
108 * the debounced function.
109 * @param {...?} var_args Arguments to pass on to the debounced function.
110 */
111 goog.async.Debouncer.prototype.fire = function(var_args) {
112 this.args_ = arguments;
113 // When this method is called, we need to prevent fire() calls from within the
114 // previous interval from calling the callback. The simplest way of doing this
115 // is to call this.stop() which calls clearTimeout, and then reschedule the
116 // timeout. However clearTimeout and setTimeout are expensive, so we just
117 // leave them untouched and when they do happen we potentially reschedule.
118 this.shouldFire_ = false;
119 if (this.timer_) {
120 this.refireAt_ = goog.now() + this.interval_;
121 return;
122 }
123 this.timer_ = goog.Timer.callOnce(this.callback_, this.interval_);
124 };
125
126
127 /**
128 * Cancels any pending action callback. The debouncer can be restarted by
129 * calling {@link #fire}.
130 */
131 goog.async.Debouncer.prototype.stop = function() {
132 if (this.timer_) {
133 goog.Timer.clear(this.timer_);
134 this.timer_ = null;
135 }
136 this.refireAt_ = null;
137 this.shouldFire_ = false;
138 this.args_ = [];
139 };
140
141
142 /**
143 * Pauses the debouncer. All pending and future action callbacks will be delayed
144 * until the debouncer is resumed. Pauses can be nested.
145 */
146 goog.async.Debouncer.prototype.pause = function() {
147 ++this.pauseCount_;
148 };
149
150
151 /**
152 * Resumes the debouncer. If doing so drops the pausing count to zero, pending
153 * action callbacks will be executed as soon as possible, but still no sooner
154 * than an interval's delay after the previous call. Future action callbacks
155 * will be executed as normal.
156 */
157 goog.async.Debouncer.prototype.resume = function() {
158 if (!this.pauseCount_) {
159 return;
160 }
161
162 --this.pauseCount_;
163 if (!this.pauseCount_ && this.shouldFire_) {
164 this.doAction_();
165 }
166 };
167
168
169 /** @override */
170 goog.async.Debouncer.prototype.disposeInternal = function() {
171 this.stop();
172 goog.async.Debouncer.base(this, 'disposeInternal');
173 };
174
175
176 /**
177 * Handler for the timer to fire the debouncer.
178 * @private
179 */
180 goog.async.Debouncer.prototype.onTimer_ = function() {
181 // There is a newer call to fire() within the debounce interval.
182 // Reschedule the callback and return.
183 if (this.refireAt_) {
184 this.timer_ =
185 goog.Timer.callOnce(this.callback_, this.refireAt_ - goog.now());
186 this.refireAt_ = null;
187 return;
188 }
189 this.timer_ = null;
190
191 if (!this.pauseCount_) {
192 this.doAction_();
193 } else {
194 this.shouldFire_ = true;
195 }
196 };
197
198
199 /**
200 * Calls the callback.
201 * @private
202 */
203 goog.async.Debouncer.prototype.doAction_ = function() {
204 this.shouldFire_ = false;
205 this.listener_.apply(null, this.args_);
206 };