# lib/goog/async/run.js

1 | // Copyright 2013 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 | goog.provide('goog.async.run');
16 |
17 | goog.require('goog.async.nextTick');
18 | goog.require('goog.async.throwException');
19 | goog.require('goog.testing.watchers');
20 |
21 |
22 | /**
23 | * Fires the provided callback just before the current callstack unwinds, or as
24 | * soon as possible after the current JS execution context.
25 | * @param {function(this:THIS)} callback
26 | * @param {THIS=} opt_context Object to use as the "this value" when calling
27 | * the provided function.
28 | * @template THIS
29 | */
30 | goog.async.run = function(callback, opt_context) {
31 | if (!goog.async.run.schedule_) {
32 | goog.async.run.initializeRunner_();
33 | }
34 | if (!goog.async.run.workQueueScheduled_) {
35 | // Nothing is currently scheduled, schedule it now.
36 | goog.async.run.schedule_();
37 | goog.async.run.workQueueScheduled_ = true;
38 | }
39 |
40 | goog.async.run.workQueue_.push(
41 | new goog.async.run.WorkItem_(callback, opt_context));
42 | };
43 |
44 |
45 | /**
46 | * Initializes the function to use to process the work queue.
47 | * @private
48 | */
49 | goog.async.run.initializeRunner_ = function() {
50 | // If native Promises are available in the browser, just schedule the callback
51 | // on a fulfilled promise, which is specified to be async, but as fast as
52 | // possible.
53 | if (goog.global.Promise && goog.global.Promise.resolve) {
54 | var promise = goog.global.Promise.resolve();
55 | goog.async.run.schedule_ = function() {
56 | promise.then(goog.async.run.processWorkQueue);
57 | };
58 | } else {
59 | goog.async.run.schedule_ = function() {
60 | goog.async.nextTick(goog.async.run.processWorkQueue);
61 | };
62 | }
63 | };
64 |
65 |
66 | /**
67 | * Forces goog.async.run to use nextTick instead of Promise.
68 | *
69 | * This should only be done in unit tests. It's useful because MockClock
70 | * replaces nextTick, but not the browser Promise implementation, so it allows
71 | * Promise-based code to be tested with MockClock.
72 | */
73 | goog.async.run.forceNextTick = function() {
74 | goog.async.run.schedule_ = function() {
75 | goog.async.nextTick(goog.async.run.processWorkQueue);
76 | };
77 | };
78 |
79 |
80 | /**
81 | * The function used to schedule work asynchronousely.
82 | * @private {function()}
83 | */
84 | goog.async.run.schedule_;
85 |
86 |
87 | /** @private {boolean} */
88 | goog.async.run.workQueueScheduled_ = false;
89 |
90 |
91 | /** @private {!Array<!goog.async.run.WorkItem_>} */
92 | goog.async.run.workQueue_ = [];
93 |
94 |
95 | if (goog.DEBUG) {
96 | /**
97 | * Reset the event queue.
98 | * @private
99 | */
100 | goog.async.run.resetQueue_ = function() {
101 | goog.async.run.workQueueScheduled_ = false;
102 | goog.async.run.workQueue_ = [];
103 | };
104 |
105 | // If there is a clock implemenation in use for testing
106 | // and it is reset, reset the queue.
107 | goog.testing.watchers.watchClockReset(goog.async.run.resetQueue_);
108 | }
109 |
110 |
111 | /**
112 | * Run any pending goog.async.run work items. This function is not intended
113 | * for general use, but for use by entry point handlers to run items ahead of
114 | * goog.async.nextTick.
115 | */
116 | goog.async.run.processWorkQueue = function() {
117 | // NOTE: additional work queue items may be pushed while processing.
118 | while (goog.async.run.workQueue_.length) {
119 | // Don't let the work queue grow indefinitely.
120 | var workItems = goog.async.run.workQueue_;
121 | goog.async.run.workQueue_ = [];
122 | for (var i = 0; i < workItems.length; i++) {
123 | var workItem = workItems[i];
124 | try {
125 | workItem.fn.call(workItem.scope);
126 | } catch (e) {
127 | goog.async.throwException(e);
128 | }
129 | }
130 | }
131 |
132 | // There are no more work items, reset the work queue.
133 | goog.async.run.workQueueScheduled_ = false;
134 | };
135 |
136 |
137 |
138 | /**
139 | * @constructor
140 | * @final
141 | * @struct
142 | * @private
143 | *
144 | * @param {function()} fn
145 | * @param {Object|null|undefined} scope
146 | */
147 | goog.async.run.WorkItem_ = function(fn, scope) {
148 | /** @const */ this.fn = fn;
149 | /** @const */ this.scope = scope;
150 | };