sync module¶
Provides an assortment of synchronisation primitives.
-
executeSoon
(func)¶ Dispatch a function to be executed on the main thread.
- Arguments
func (function) – Function to be executed.
-
class
MessageManagerDestroyedPromise
(messageManager)¶ Detects when the specified message manager has been destroyed.
One can observe the removal and detachment of a content browser (<xul:browser>) or a chrome window by its message manager disconnecting.
When a browser is associated with a tab, this is safer than only relying on the event TabClose which signalises the _intent to_ remove a tab and consequently would lead to the destruction of the content browser and its browser message manager.
When closing a chrome window it is safer than only relying on the event ‘unload’ which signalises the _intent to_ close the chrome window and consequently would lead to the destruction of the window and its window message manager.
- Arguments
messageManager (MessageListenerManager) – The message manager to observe for its disconnect state. Use the browser message manager when closing a content browser, and the window message manager when closing a chrome window.
- Returns
Promise – A promise that resolves when the message manager has been destroyed.
-
class
PollPromise
(func, timeout, interval=10)¶ Runs a Promise-like function off the main thread until it is resolved through
resolve
orrejected
callbacks. The function is guaranteed to be run at least once, irregardless of the timeout.The
func
is evaluated everyinterval
for as long as its runtime duration does not exceedinterval
. Evaluations occur sequentially, meaning that evaluations offunc
are queued if the runtime evaluation duration offunc
is greater thaninterval
.func
is given two arguments,resolve
andreject
, of which one must be called for the evaluation to complete. Callingresolve
with an argument indicates that the expected wait condition was met and will return the passed value to the caller. Conversely, callingreject
will evaluatefunc
again until thetimeout
duration has elapsed orfunc
throws. The passed value toreject
will also be returned to the caller once the wait has expired.Usage:
let els = new PollPromise((resolve, reject) => { let res = document.querySelectorAll("p"); if (res.length > 0) { resolve(Array.from(res)); } else { reject([]); } }, {timeout: 1000});
- Arguments
func (Condition) – Function to run off the main thread.
timeout (number) – timeout Desired timeout if wanted. If 0 or less than the runtime evaluation time of
func
,func
is guaranteed to run at least once. Defaults to using no timeout.interval (number) – interval Duration between each poll of
func
in milliseconds. Defaults to 10 milliseconds.
- Throws
* – If
func
throws, its error is propagated.TypeError – If timeout or interval` are not numbers.
RangeError – If timeout or interval are not unsigned integers.
- Returns
Promise.<*> – Yields the value passed to
func
’sresolve
orreject
callbacks.
-
class
Sleep
(timeout)¶ Pauses for the given duration.
- Arguments
timeout (number) – Duration to wait before fulfilling promise in milliseconds.
- Throws
TypeError – If timeout is not a number.
RangeError – If timeout is not an unsigned integer.
- Returns
Promise – Promise that fulfills when the timeout is elapsed.
-
class
TimedPromise
(func, timeout, throws=TimeoutError)¶ Represents the timed, eventual completion (or failure) of an asynchronous operation, and its resulting value.
In contrast to a regular Promise, it times out after
timeout
.- Arguments
func (Condition) – Function to run, which will have its
reject
callback invoked after thetimeout
duration is reached. It is given two callbacks:resolve(value)
andreject(error)
.timeout (timeout) –
condition
’sreject
callback will be called after this timeout, given in milliseconds. By default 1500 ms in an optimised build and 4500 ms in debug builds.throws (Error) – throws When the
timeout
is hit, this error class will be thrown. If it is null, no error is thrown and the promise is instead resolved on timeout.
- Throws
TypeError – If timeout is not a number.
RangeError – If timeout is not an unsigned integer.
- Returns
Promise.<*> – Timed promise.
-
waitForEvent
(subject, eventName, options)¶ Wait for an event to be fired on a specified element.
This method has been duplicated from BrowserTestUtils.jsm.
Because this function is intended for testing, any error in checkFn will cause the returned promise to be rejected instead of waiting for the next event, since this is probably a bug in the test.
Usage:
let promiseEvent = waitForEvent(element, "eventName"); // Do some processing here that will cause the event to be fired // ... // Now wait until the Promise is fulfilled let receivedEvent = await promiseEvent;
The promise resolution/rejection handler for the returned promise is guaranteed not to be called until the next event tick after the event listener gets called, so that all other event listeners for the element are executed before the handler is executed:
let promiseEvent = waitForEvent(element, "eventName"); // Same event tick here. await promiseEvent; // Next event tick here.
If some code, such like adding yet another event listener, needs to be executed in the same event tick, use raw addEventListener instead and place the code inside the event listener:
element.addEventListener("load", () => { // Add yet another event listener in the same event tick as the load // event listener. p = waitForEvent(element, "ready"); }, { once: true });
- Arguments
subject (Element) – The element that should receive the event.
eventName (string) – Name of the event to listen to.
options (Object) – Extra options.
options.capture (boolean) – True to use a capturing listener.
options.checkFn (function) – Called with the
Event
object as argument, should returntrue
if the event is the expected one, orfalse
if it should be ignored and listening should continue. If not specified, the first event with the specified name resolves the returned promise.options.wantsUntrusted (boolean) – True to receive synthetic events dispatched by web content.
- Returns
Promise.<Event> – Promise which resolves to the received
Event
object, or rejects in case of a failure.
-
waitForMessage
(messageManager, messageName, options)¶ Wait for a message to be fired from a particular message manager.
This method has been duplicated from BrowserTestUtils.jsm.
- Arguments
messageManager (nsIMessageManager) – The message manager that should be used.
messageName (string) – The message to wait for.
options (Object) – Extra options.
options.checkFn (function) – Called with the
Message
object as argument, should returntrue
if the message is the expected one, orfalse
if it should be ignored and listening should continue. If not specified, the first message with the specified name resolves the returned promise.
- Returns
Promise.<Object> – Promise which resolves to the data property of the received
Message
.
-
waitForObserverTopic
(topic, options)¶ Wait for the specified observer topic to be observed.
This method has been duplicated from TestUtils.jsm.
Because this function is intended for testing, any error in checkFn will cause the returned promise to be rejected instead of waiting for the next notification, since this is probably a bug in the test.
- Arguments
topic (string) – The topic to observe.
options (Object) – Extra options.
options.checkFn (function) – Called with
subject
, anddata
as arguments, should return true if the notification is the expected one, or false if it should be ignored and listening should continue. If not specified, the first notification for the specified topic resolves the returned promise.
- Returns
Promise.<Array.<String, Object>> – Promise which resolves to an array of
subject
, anddata
from the observed notification.