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