Debian Codegraph @

closure-library/closure/goog/async/nexttick.js

raw
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 /**
16 * @fileoverview Provides a function to schedule running a function as soon
17 * as possible after the current JS execution stops and yields to the event
18 * loop.
19 *
20 */
21
22 goog.provide('goog.async.nextTick');
23 goog.provide('goog.async.throwException');
24
25 goog.require('goog.debug.entryPointRegistry');
26 goog.require('goog.dom.TagName');
27 goog.require('goog.functions');
28 goog.require('goog.labs.userAgent.browser');
29 goog.require('goog.labs.userAgent.engine');
30
31
32 /**
33 * Throw an item without interrupting the current execution context. For
34 * example, if processing a group of items in a loop, sometimes it is useful
35 * to report an error while still allowing the rest of the batch to be
36 * processed.
37 * @param {*} exception
38 */
39 goog.async.throwException = function(exception) {
40 // Each throw needs to be in its own context.
41 goog.global.setTimeout(function() { throw exception; }, 0);
42 };
43
44
45 /**
46 * Fires the provided callbacks as soon as possible after the current JS
47 * execution context. setTimeout(…, 0) takes at least 4ms when called from
48 * within another setTimeout(…, 0) for legacy reasons.
49 *
50 * This will not schedule the callback as a microtask (i.e. a task that can
51 * preempt user input or networking callbacks). It is meant to emulate what
52 * setTimeout(_, 0) would do if it were not throttled. If you desire microtask
53 * behavior, use {@see goog.Promise} instead.
54 *
55 * @param {function(this:SCOPE)} callback Callback function to fire as soon as
56 * possible.
57 * @param {SCOPE=} opt_context Object in whose scope to call the listener.
58 * @param {boolean=} opt_useSetImmediate Avoid the IE workaround that
59 * ensures correctness at the cost of speed. See comments for details.
60 * @template SCOPE
61 */
62 goog.async.nextTick = function(callback, opt_context, opt_useSetImmediate) {
63 var cb = callback;
64 if (opt_context) {
65 cb = goog.bind(callback, opt_context);
66 }
67 cb = goog.async.nextTick.wrapCallback_(cb);
68 // Note we do allow callers to also request setImmediate if they are willing
69 // to accept the possible tradeoffs of incorrectness in exchange for speed.
70 // The IE fallback of readystate change is much slower. See useSetImmediate_
71 // for details.
72 if (goog.isFunction(goog.global.setImmediate) &&
73 (opt_useSetImmediate || goog.async.nextTick.useSetImmediate_())) {
74 goog.global.setImmediate(cb);
75 return;
76 }
77
78 // Look for and cache the custom fallback version of setImmediate.
79 if (!goog.async.nextTick.setImmediate_) {
80 goog.async.nextTick.setImmediate_ =
81 goog.async.nextTick.getSetImmediateEmulator_();
82 }
83 goog.async.nextTick.setImmediate_(cb);
84 };
85
86
87 /**
88 * Returns whether should use setImmediate implementation currently on window.
89 *
90 * window.setImmediate was introduced and currently only supported by IE10+,
91 * but due to a bug in the implementation it is not guaranteed that
92 * setImmediate is faster than setTimeout nor that setImmediate N is before
93 * setImmediate N+1. That is why we do not use the native version if
94 * available. We do, however, call setImmediate if it is a non-native function
95 * because that indicates that it has been replaced by goog.testing.MockClock
96 * which we do want to support.
97 * See
98 * http://connect.microsoft.com/IE/feedback/details/801823/setimmediate-and-messagechannel-are-broken-in-ie10
99 *
100 * @return {boolean} Whether to use the implementation of setImmediate defined
101 * on Window.
102 * @private
103 */
104 goog.async.nextTick.useSetImmediate_ = function() {
105 // Not a browser environment.
106 if (!goog.global.Window || !goog.global.Window.prototype) {
107 return true;
108 }
109
110 // MS Edge has window.setImmediate natively, but it's not on Window.prototype.
111 // Also, there's no clean way to detect if the goog.global.setImmediate has
112 // been replaced by mockClock as its replacement also shows up as "[native
113 // code]" when using toString. Therefore, just always use
114 // goog.global.setImmediate for Edge. It's unclear if it suffers the same
115 // issues as IE10/11, but based on
116 // https://dev.modern.ie/testdrive/demos/setimmediatesorting/
117 // it seems they've been working to ensure it's WAI.
118 if (goog.labs.userAgent.browser.isEdge() ||
119 goog.global.Window.prototype.setImmediate != goog.global.setImmediate) {
120 // Something redefined setImmediate in which case we decide to use it (This
121 // is so that we use the mockClock setImmediate).
122 return true;
123 }
124
125 return false;
126 };
127
128
129 /**
130 * Cache for the setImmediate implementation.
131 * @type {function(function())}
132 * @private
133 */
134 goog.async.nextTick.setImmediate_;
135
136
137 /**
138 * Determines the best possible implementation to run a function as soon as
139 * the JS event loop is idle.
140 * @return {function(function())} The "setImmediate" implementation.
141 * @private
142 */
143 goog.async.nextTick.getSetImmediateEmulator_ = function() {
144 // Create a private message channel and use it to postMessage empty messages
145 // to ourselves.
146 /** @type {!Function|undefined} */
147 var Channel = goog.global['MessageChannel'];
148 // If MessageChannel is not available and we are in a browser, implement
149 // an iframe based polyfill in browsers that have postMessage and
150 // document.addEventListener. The latter excludes IE8 because it has a
151 // synchronous postMessage implementation.
152 if (typeof Channel === 'undefined' && typeof window !== 'undefined' &&
153 window.postMessage && window.addEventListener &&
154 // Presto (The old pre-blink Opera engine) has problems with iframes
155 // and contentWindow.
156 !goog.labs.userAgent.engine.isPresto()) {
157 /** @constructor */
158 Channel = function() {
159 // Make an empty, invisible iframe.
160 var iframe = /** @type {!HTMLIFrameElement} */ (
161 document.createElement(String(goog.dom.TagName.IFRAME)));
162 iframe.style.display = 'none';
163 iframe.src = '';
164 document.documentElement.appendChild(iframe);
165 var win = iframe.contentWindow;
166 var doc = win.document;
167 doc.open();
168 doc.write('');
169 doc.close();
170 // Do not post anything sensitive over this channel, as the workaround for
171 // pages with file: origin could allow that information to be modified or
172 // intercepted.
173 var message = 'callImmediate' + Math.random();
174 // The same origin policy rejects attempts to postMessage from file: urls
175 // unless the origin is '*'.
176 var origin = win.location.protocol == 'file:' ?
177 '*' :
178 win.location.protocol + '//' + win.location.host;
179 var onmessage = goog.bind(function(e) {
180 // Validate origin and message to make sure that this message was
181 // intended for us. If the origin is set to '*' (see above) only the
182 // message needs to match since, for example, '*' != 'file://'. Allowing
183 // the wildcard is ok, as we are not concerned with security here.
184 if ((origin != '*' && e.origin != origin) || e.data != message) {
185 return;
186 }
187 this['port1'].onmessage();
188 }, this);
189 win.addEventListener('message', onmessage, false);
190 this['port1'] = {};
191 this['port2'] = {
192 postMessage: function() { win.postMessage(message, origin); }
193 };
194 };
195 }
196 if (typeof Channel !== 'undefined' && !goog.labs.userAgent.browser.isIE()) {
197 // Exclude all of IE due to
198 // http://codeforhire.com/2013/09/21/setimmediate-and-messagechannel-broken-on-internet-explorer-10/
199 // which allows starving postMessage with a busy setTimeout loop.
200 // This currently affects IE10 and IE11 which would otherwise be able
201 // to use the postMessage based fallbacks.
202 var channel = new Channel();
203 // Use a fifo linked list to call callbacks in the right order.
204 var head = {};
205 var tail = head;
206 channel['port1'].onmessage = function() {
207 if (goog.isDef(head.next)) {
208 head = head.next;
209 var cb = head.cb;
210 head.cb = null;
211 cb();
212 }
213 };
214 return function(cb) {
215 tail.next = {cb: cb};
216 tail = tail.next;
217 channel['port2'].postMessage(0);
218 };
219 }
220 // Implementation for IE6 to IE10: Script elements fire an asynchronous
221 // onreadystatechange event when inserted into the DOM.
222 if (typeof document !== 'undefined' &&
223 'onreadystatechange' in
224 document.createElement(String(goog.dom.TagName.SCRIPT))) {
225 return function(cb) {
226 var script = document.createElement(String(goog.dom.TagName.SCRIPT));
227 script.onreadystatechange = function() {
228 // Clean up and call the callback.
229 script.onreadystatechange = null;
230 script.parentNode.removeChild(script);
231 script = null;
232 cb();
233 cb = null;
234 };
235 document.documentElement.appendChild(script);
236 };
237 }
238 // Fall back to setTimeout with 0. In browsers this creates a delay of 5ms
239 // or more.
240 // NOTE(user): This fallback is used for IE11.
241 return function(cb) {
242 goog.global.setTimeout(/** @type {function()} */ (cb), 0);
243 };
244 };
245
246
247 /**
248 * Helper function that is overrided to protect callbacks with entry point
249 * monitor if the application monitors entry points.
250 * @param {function()} callback Callback function to fire as soon as possible.
251 * @return {function()} The wrapped callback.
252 * @private
253 */
254 goog.async.nextTick.wrapCallback_ = goog.functions.identity;
255
256
257 // Register the callback function as an entry point, so that it can be
258 // monitored for exception handling, etc. This has to be done in this file
259 // since it requires special code to handle all browsers.
260 goog.debug.entryPointRegistry.register(
261 /**
262 * @param {function(!Function): !Function} transformer The transforming
263 * function.
264 */
265 function(transformer) { goog.async.nextTick.wrapCallback_ = transformer; });