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 or rejected callbacks. The function is guaranteed to be run at least once, irregardless of the timeout.

The func is evaluated every interval for as long as its runtime duration does not exceed interval. Evaluations occur sequentially, meaning that evaluations of func are queued if the runtime evaluation duration of func is greater than interval.

func is given two arguments, resolve and reject, of which one must be called for the evaluation to complete. Calling resolve with an argument indicates that the expected wait condition was met and will return the passed value to the caller. Conversely, calling reject will evaluate func again until the timeout duration has elapsed or func throws. The passed value to reject 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’s resolve or reject 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, options)

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 the timeout duration is reached. It is given two callbacks: resolve(value) and reject(error).

  • options (Object()) –

  • options.errorMessage (String()) – Message to use for the thrown error.

  • options.timeout (number()) – condition’s reject callback will be called after this timeout, given in milliseconds. By default 1500 ms in an optimised build and 4500 ms in debug builds.

  • options.throws (Error()) – 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 return true if the event is the expected one, or false 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 return true if the message is the expected one, or false 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, and data 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, and data from the observed notification.