Debian Codegraph @

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

raw
1 // Copyright 2007 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.Throttle class.
17 *
18 * @see ../demos/timers.html
19 */
20
21 goog.provide('goog.Throttle');
22 goog.provide('goog.async.Throttle');
23
24 goog.require('goog.Disposable');
25 goog.require('goog.Timer');
26
27
28
29 /**
30 * Throttle will perform an action that is passed in no more than once
31 * per interval (specified in milliseconds). If it gets multiple signals
32 * to perform the action while it is waiting, it will only perform the action
33 * once at the end of the interval.
34 * @param {function(this: T, ...?)} listener Function to callback when the
35 * action is triggered.
36 * @param {number} interval Interval over which to throttle. The listener can
37 * only be called once per interval.
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.Throttle = function(listener, interval, opt_handler) {
46 goog.async.Throttle.base(this, 'constructor');
47
48 /**
49 * Function to callback
50 * @type {function(this: T, ...?)}
51 * @private
52 */
53 this.listener_ =
54 opt_handler != null ? goog.bind(listener, opt_handler) : listener;
55
56 /**
57 * Interval for the throttle time
58 * @type {number}
59 * @private
60 */
61 this.interval_ = interval;
62
63 /**
64 * Cached callback function invoked after the throttle timeout completes
65 * @type {Function}
66 * @private
67 */
68 this.callback_ = goog.bind(this.onTimer_, this);
69
70 /**
71 * The last arguments passed into {@code fire}.
72 * @private {!IArrayLike}
73 */
74 this.args_ = [];
75 };
76 goog.inherits(goog.async.Throttle, goog.Disposable);
77
78
79
80 /**
81 * A deprecated alias.
82 * @deprecated Use goog.async.Throttle instead.
83 * @constructor
84 * @final
85 */
86 goog.Throttle = goog.async.Throttle;
87
88
89 /**
90 * Indicates that the action is pending and needs to be fired.
91 * @type {boolean}
92 * @private
93 */
94 goog.async.Throttle.prototype.shouldFire_ = false;
95
96
97 /**
98 * Indicates the count of nested pauses currently in effect on the throttle.
99 * When this count is not zero, fired actions will be postponed until the
100 * throttle is resumed enough times to drop the pause count to zero.
101 * @type {number}
102 * @private
103 */
104 goog.async.Throttle.prototype.pauseCount_ = 0;
105
106
107 /**
108 * Timer for scheduling the next callback
109 * @type {?number}
110 * @private
111 */
112 goog.async.Throttle.prototype.timer_ = null;
113
114
115 /**
116 * Notifies the throttle that the action has happened. It will throttle the call
117 * so that the callback is not called too often according to the interval
118 * parameter passed to the constructor, passing the arguments from the last call
119 * of this function into the throttled function.
120 * @param {...?} var_args Arguments to pass on to the throttled function.
121 */
122 goog.async.Throttle.prototype.fire = function(var_args) {
123 this.args_ = arguments;
124 if (!this.timer_ && !this.pauseCount_) {
125 this.doAction_();
126 } else {
127 this.shouldFire_ = true;
128 }
129 };
130
131
132 /**
133 * Cancels any pending action callback. The throttle can be restarted by
134 * calling {@link #fire}.
135 */
136 goog.async.Throttle.prototype.stop = function() {
137 if (this.timer_) {
138 goog.Timer.clear(this.timer_);
139 this.timer_ = null;
140 this.shouldFire_ = false;
141 this.args_ = [];
142 }
143 };
144
145
146 /**
147 * Pauses the throttle. All pending and future action callbacks will be
148 * delayed until the throttle is resumed. Pauses can be nested.
149 */
150 goog.async.Throttle.prototype.pause = function() {
151 this.pauseCount_++;
152 };
153
154
155 /**
156 * Resumes the throttle. If doing so drops the pausing count to zero, pending
157 * action callbacks will be executed as soon as possible, but still no sooner
158 * than an interval's delay after the previous call. Future action callbacks
159 * will be executed as normal.
160 */
161 goog.async.Throttle.prototype.resume = function() {
162 this.pauseCount_--;
163 if (!this.pauseCount_ && this.shouldFire_ && !this.timer_) {
164 this.shouldFire_ = false;
165 this.doAction_();
166 }
167 };
168
169
170 /** @override */
171 goog.async.Throttle.prototype.disposeInternal = function() {
172 goog.async.Throttle.base(this, 'disposeInternal');
173 this.stop();
174 };
175
176
177 /**
178 * Handler for the timer to fire the throttle
179 * @private
180 */
181 goog.async.Throttle.prototype.onTimer_ = function() {
182 this.timer_ = null;
183
184 if (this.shouldFire_ && !this.pauseCount_) {
185 this.shouldFire_ = false;
186 this.doAction_();
187 }
188 };
189
190
191 /**
192 * Calls the callback
193 * @private
194 */
195 goog.async.Throttle.prototype.doAction_ = function() {
196 this.timer_ = goog.Timer.callOnce(this.callback_, this.interval_);
197 this.listener_.apply(null, this.args_);
198 };