1
// Copyright 2011 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
/**
17
 * @fileoverview Utility class to manage the mathematics behind computing an
18
 * exponential backoff model.  Given an initial backoff value and a maximum
19
 * backoff value, every call to backoff() will double the value until maximum
20
 * backoff value is reached.
21
 *
22
 */
23

24

25
goog.provide('goog.math.ExponentialBackoff');
26

27
goog.require('goog.asserts');
28

29

30

31
/**
32
 * @struct
33
 * @constructor
34
 *
35
 * @param {number} initialValue The initial backoff value.
36
 * @param {number} maxValue The maximum backoff value.
37
 * @param {number=} opt_randomFactor When set, adds randomness to the backoff
38
 *     and decay to avoid a thundering herd problem. Should be a number between
39
 *     0 and 1, where 0 means no randomness and 1 means a factor of 0x to 2x.
40
 * @param {number=} opt_backoffFactor The factor to backoff by. Defaults to 2.
41
 *     Should be a number greater than 1.
42
 * @param {number=} opt_decayFactor The factor to decay by. Defaults to 2.
43
 *     Should be a number between greater than one.
44
 */
45
goog.math.ExponentialBackoff = function(
46
    initialValue, maxValue, opt_randomFactor, opt_backoffFactor,
47
    opt_decayFactor) {
48
  goog.asserts.assert(
49
      initialValue > 0, 'Initial value must be greater than zero.');
50
  goog.asserts.assert(
51
      maxValue >= initialValue,
52
      'Max value should be at least as large as initial value.');
53

54
  if (goog.isDef(opt_randomFactor)) {
55
    goog.asserts.assert(
56
        opt_randomFactor >= 0 && opt_randomFactor <= 1,
57
        'Randomness factor should be between 0 and 1.');
58
  }
59

60
  if (goog.isDef(opt_backoffFactor)) {
61
    goog.asserts.assert(
62
        opt_backoffFactor > 1, 'Backoff factor should be greater than 1');
63
  }
64

65
  if (goog.isDef(opt_decayFactor)) {
66
    goog.asserts.assert(
67
        opt_decayFactor >= 1, 'Decay factor should be greater than 1');
68
  }
69

70
  /**
71
   * @type {number}
72
   * @private
73
   */
74
  this.initialValue_ = initialValue;
75

76
  /**
77
   * @type {number}
78
   * @private
79
   */
80
  this.maxValue_ = maxValue;
81

82
  /**
83
   * The current backoff value.
84
   * @type {number}
85
   * @private
86
   */
87
  this.currValue_ = initialValue;
88

89
  /**
90
   * The current backoff value minus the random wait (if there is any).
91
   * @type {number}
92
   * @private
93
   */
94
  this.currBaseValue_ = initialValue;
95

96
  /**
97
   * The random factor to apply to the backoff value to avoid a thundering herd
98
   * problem. Should be a number between 0 and 1, where 0 means no randomness
99
   * and 1 means a factor of 0x to 2x.
100
   * @type {number}
101
   * @private
102
   */
103
  this.randomFactor_ = opt_randomFactor || 0;
104

105
  /**
106
   * Factor to backoff by.
107
   * @type {number}
108
   * @private
109
   */
110
  this.backoffFactor_ = opt_backoffFactor || 2;
111

112
  /**
113
   * Factor to decay by.
114
   * @type {number}
115
   * @private
116
   */
117
  this.decayFactor_ = opt_decayFactor || 2;
118
};
119

120

121
/**
122
 * The number of backoffs that have happened.
123
 * @type {number}
124
 * @private
125
 */
126
goog.math.ExponentialBackoff.prototype.currBackoffCount_ = 0;
127

128

129
/**
130
 * The number of decays that have happened.
131
 * @type {number}
132
 * @private
133
 */
134
goog.math.ExponentialBackoff.prototype.currDecayCount_ = 0;
135

136

137
/**
138
 * Resets the backoff value to its initial value.
139
 */
140
goog.math.ExponentialBackoff.prototype.reset = function() {
141
  this.currValue_ = this.initialValue_;
142
  this.currBaseValue_ = this.initialValue_;
143
  this.currBackoffCount_ = 0;
144
  this.currDecayCount_ = 0;
145
};
146

147

148
/**
149
 * @return {number} The current backoff value.
150
 */
151
goog.math.ExponentialBackoff.prototype.getValue = function() {
152
  return this.currValue_;
153
};
154

155

156
/**
157
 * @return {number} The number of times this class has backed off.
158
 */
159
goog.math.ExponentialBackoff.prototype.getBackoffCount = function() {
160
  return this.currBackoffCount_;
161
};
162

163

164
/**
165
 * @return {number} The number of times this class has decayed.
166
 */
167
goog.math.ExponentialBackoff.prototype.getDecayCount = function() {
168
  return this.currDecayCount_;
169
};
170

171

172
/**
173
 * Initiates a backoff.
174
 */
175
goog.math.ExponentialBackoff.prototype.backoff = function() {
176
  // If we haven't hit the maximum value yet, keep increasing the base value.
177
  this.currBaseValue_ =
178
      Math.min(this.maxValue_, this.currBaseValue_ * this.backoffFactor_);
179

180
  var randomWait = this.randomFactor_ ?
181
      Math.round(
182
          this.randomFactor_ * (Math.random() - 0.5) * 2 *
183
          this.currBaseValue_) :
184
      0;
185
  this.currValue_ = Math.min(this.maxValue_, this.currBaseValue_ + randomWait);
186
  this.currBackoffCount_++;
187
};
188

189

190
/**
191
 * Initiates a decay.
192
 */
193
goog.math.ExponentialBackoff.prototype.decay = function() {
194
  // If we haven't hit the initial value yet, keep decreasing the base value.
195
  this.currBaseValue_ =
196
      Math.max(this.initialValue_, this.currBaseValue_ / this.decayFactor_);
197

198
  var randomWait = this.randomFactor_ ?
199
      Math.round(
200
          this.randomFactor_ * (Math.random() - 0.5) * 2 *
201
          this.currBaseValue_) :
202
      0;
203
  this.currValue_ =
204
      Math.max(this.initialValue_, this.currBaseValue_ + randomWait);
205
  this.currDecayCount_++;
206
};
207

208