Debian Codegraph @

closure-library/closure/goog/disposable/disposable.js

raw
1 // Copyright 2005 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 Implements the disposable interface. The dispose method is used
17 * to clean up references and resources.
18 * @author [email protected] (Erik Arvidsson)
19 */
20
21
22 goog.provide('goog.Disposable');
23 goog.provide('goog.dispose');
24 goog.provide('goog.disposeAll');
25
26 goog.require('goog.disposable.IDisposable');
27
28
29
30 /**
31 * Class that provides the basic implementation for disposable objects. If your
32 * class holds one or more references to COM objects, DOM nodes, or other
33 * disposable objects, it should extend this class or implement the disposable
34 * interface (defined in goog.disposable.IDisposable).
35 * @constructor
36 * @implements {goog.disposable.IDisposable}
37 */
38 goog.Disposable = function() {
39 /**
40 * If monitoring the goog.Disposable instances is enabled, stores the creation
41 * stack trace of the Disposable instance.
42 * @type {string|undefined}
43 */
44 this.creationStack;
45
46 if (goog.Disposable.MONITORING_MODE != goog.Disposable.MonitoringMode.OFF) {
47 if (goog.Disposable.INCLUDE_STACK_ON_CREATION) {
48 this.creationStack = new Error().stack;
49 }
50 goog.Disposable.instances_[goog.getUid(this)] = this;
51 }
52 // Support sealing
53 this.disposed_ = this.disposed_;
54 this.onDisposeCallbacks_ = this.onDisposeCallbacks_;
55 };
56
57
58 /**
59 * @enum {number} Different monitoring modes for Disposable.
60 */
61 goog.Disposable.MonitoringMode = {
62 /**
63 * No monitoring.
64 */
65 OFF: 0,
66 /**
67 * Creating and disposing the goog.Disposable instances is monitored. All
68 * disposable objects need to call the {@code goog.Disposable} base
69 * constructor. The PERMANENT mode must be switched on before creating any
70 * goog.Disposable instances.
71 */
72 PERMANENT: 1,
73 /**
74 * INTERACTIVE mode can be switched on and off on the fly without producing
75 * errors. It also doesn't warn if the disposable objects don't call the
76 * {@code goog.Disposable} base constructor.
77 */
78 INTERACTIVE: 2
79 };
80
81
82 /**
83 * @define {number} The monitoring mode of the goog.Disposable
84 * instances. Default is OFF. Switching on the monitoring is only
85 * recommended for debugging because it has a significant impact on
86 * performance and memory usage. If switched off, the monitoring code
87 * compiles down to 0 bytes.
88 */
89 goog.define('goog.Disposable.MONITORING_MODE', 0);
90
91
92 /**
93 * @define {boolean} Whether to attach creation stack to each created disposable
94 * instance; This is only relevant for when MonitoringMode != OFF.
95 */
96 goog.define('goog.Disposable.INCLUDE_STACK_ON_CREATION', true);
97
98
99 /**
100 * Maps the unique ID of every undisposed {@code goog.Disposable} object to
101 * the object itself.
102 * @type {!Object<number, !goog.Disposable>}
103 * @private
104 */
105 goog.Disposable.instances_ = {};
106
107
108 /**
109 * @return {!Array<!goog.Disposable>} All {@code goog.Disposable} objects that
110 * haven't been disposed of.
111 */
112 goog.Disposable.getUndisposedObjects = function() {
113 var ret = [];
114 for (var id in goog.Disposable.instances_) {
115 if (goog.Disposable.instances_.hasOwnProperty(id)) {
116 ret.push(goog.Disposable.instances_[Number(id)]);
117 }
118 }
119 return ret;
120 };
121
122
123 /**
124 * Clears the registry of undisposed objects but doesn't dispose of them.
125 */
126 goog.Disposable.clearUndisposedObjects = function() {
127 goog.Disposable.instances_ = {};
128 };
129
130
131 /**
132 * Whether the object has been disposed of.
133 * @type {boolean}
134 * @private
135 */
136 goog.Disposable.prototype.disposed_ = false;
137
138
139 /**
140 * Callbacks to invoke when this object is disposed.
141 * @type {Array<!Function>}
142 * @private
143 */
144 goog.Disposable.prototype.onDisposeCallbacks_;
145
146
147 /**
148 * @return {boolean} Whether the object has been disposed of.
149 * @override
150 */
151 goog.Disposable.prototype.isDisposed = function() {
152 return this.disposed_;
153 };
154
155
156 /**
157 * @return {boolean} Whether the object has been disposed of.
158 * @deprecated Use {@link #isDisposed} instead.
159 */
160 goog.Disposable.prototype.getDisposed = goog.Disposable.prototype.isDisposed;
161
162
163 /**
164 * Disposes of the object. If the object hasn't already been disposed of, calls
165 * {@link #disposeInternal}. Classes that extend {@code goog.Disposable} should
166 * override {@link #disposeInternal} in order to delete references to COM
167 * objects, DOM nodes, and other disposable objects. Reentrant.
168 *
169 * @return {void} Nothing.
170 * @override
171 */
172 goog.Disposable.prototype.dispose = function() {
173 if (!this.disposed_) {
174 // Set disposed_ to true first, in case during the chain of disposal this
175 // gets disposed recursively.
176 this.disposed_ = true;
177 this.disposeInternal();
178 if (goog.Disposable.MONITORING_MODE != goog.Disposable.MonitoringMode.OFF) {
179 var uid = goog.getUid(this);
180 if (goog.Disposable.MONITORING_MODE ==
181 goog.Disposable.MonitoringMode.PERMANENT &&
182 !goog.Disposable.instances_.hasOwnProperty(uid)) {
183 throw new Error(
184 this + ' did not call the goog.Disposable base ' +
185 'constructor or was disposed of after a clearUndisposedObjects ' +
186 'call');
187 }
188 delete goog.Disposable.instances_[uid];
189 }
190 }
191 };
192
193
194 /**
195 * Associates a disposable object with this object so that they will be disposed
196 * together.
197 * @param {goog.disposable.IDisposable} disposable that will be disposed when
198 * this object is disposed.
199 */
200 goog.Disposable.prototype.registerDisposable = function(disposable) {
201 this.addOnDisposeCallback(goog.partial(goog.dispose, disposable));
202 };
203
204
205 /**
206 * Invokes a callback function when this object is disposed. Callbacks are
207 * invoked in the order in which they were added. If a callback is added to
208 * an already disposed Disposable, it will be called immediately.
209 * @param {function(this:T):?} callback The callback function.
210 * @param {T=} opt_scope An optional scope to call the callback in.
211 * @template T
212 */
213 goog.Disposable.prototype.addOnDisposeCallback = function(callback, opt_scope) {
214 if (this.disposed_) {
215 goog.isDef(opt_scope) ? callback.call(opt_scope) : callback();
216 return;
217 }
218 if (!this.onDisposeCallbacks_) {
219 this.onDisposeCallbacks_ = [];
220 }
221
222 this.onDisposeCallbacks_.push(
223 goog.isDef(opt_scope) ? goog.bind(callback, opt_scope) : callback);
224 };
225
226
227 /**
228 * Deletes or nulls out any references to COM objects, DOM nodes, or other
229 * disposable objects. Classes that extend {@code goog.Disposable} should
230 * override this method.
231 * Not reentrant. To avoid calling it twice, it must only be called from the
232 * subclass' {@code disposeInternal} method. Everywhere else the public
233 * {@code dispose} method must be used.
234 * For example:
235 * <pre>
236 * mypackage.MyClass = function() {
237 * mypackage.MyClass.base(this, 'constructor');
238 * // Constructor logic specific to MyClass.
239 * ...
240 * };
241 * goog.inherits(mypackage.MyClass, goog.Disposable);
242 *
243 * mypackage.MyClass.prototype.disposeInternal = function() {
244 * // Dispose logic specific to MyClass.
245 * ...
246 * // Call superclass's disposeInternal at the end of the subclass's, like
247 * // in C++, to avoid hard-to-catch issues.
248 * mypackage.MyClass.base(this, 'disposeInternal');
249 * };
250 * </pre>
251 * @protected
252 */
253 goog.Disposable.prototype.disposeInternal = function() {
254 if (this.onDisposeCallbacks_) {
255 while (this.onDisposeCallbacks_.length) {
256 this.onDisposeCallbacks_.shift()();
257 }
258 }
259 };
260
261
262 /**
263 * Returns True if we can verify the object is disposed.
264 * Calls {@code isDisposed} on the argument if it supports it. If obj
265 * is not an object with an isDisposed() method, return false.
266 * @param {*} obj The object to investigate.
267 * @return {boolean} True if we can verify the object is disposed.
268 */
269 goog.Disposable.isDisposed = function(obj) {
270 if (obj && typeof obj.isDisposed == 'function') {
271 return obj.isDisposed();
272 }
273 return false;
274 };
275
276
277 /**
278 * Calls {@code dispose} on the argument if it supports it. If obj is not an
279 * object with a dispose() method, this is a no-op.
280 * @param {*} obj The object to dispose of.
281 */
282 goog.dispose = function(obj) {
283 if (obj && typeof obj.dispose == 'function') {
284 obj.dispose();
285 }
286 };
287
288
289 /**
290 * Calls {@code dispose} on each member of the list that supports it. (If the
291 * member is an ArrayLike, then {@code goog.disposeAll()} will be called
292 * recursively on each of its members.) If the member is not an object with a
293 * {@code dispose()} method, then it is ignored.
294 * @param {...*} var_args The list.
295 */
296 goog.disposeAll = function(var_args) {
297 for (var i = 0, len = arguments.length; i < len; ++i) {
298 var disposable = arguments[i];
299 if (goog.isArrayLike(disposable)) {
300 goog.disposeAll.apply(null, disposable);
301 } else {
302 goog.dispose(disposable);
303 }
304 }
305 };