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