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
};
199

200