Bug 1519407 - Add documentation to Window.webidl about promiseDocumentFlushed and subframe swaps. r=Ehsan
authorMike Conley <mconley@mozilla.com>
Tue, 15 Jan 2019 21:38:31 +0000
changeset 511094 959450489bcfc84a4c01cbae0e58b2b0455851e8
parent 511093 f5e32a61d19437884f4331455fc87e6e4aa6f5c6
child 511095 0aba112c5ad99d2f3b6045ebc85f5035e5d5be99
push id10547
push userffxbld-merge
push dateMon, 21 Jan 2019 13:03:58 +0000
treeherdermozilla-beta@24ec1916bffe [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersEhsan
bugs1519407
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1519407 - Add documentation to Window.webidl about promiseDocumentFlushed and subframe swaps. r=Ehsan Differential Revision: https://phabricator.services.mozilla.com/D16471
dom/webidl/Window.webidl
--- a/dom/webidl/Window.webidl
+++ b/dom/webidl/Window.webidl
@@ -484,16 +484,31 @@ partial interface Window {
    *
    *   The callback will be called asynchronously if a flush is pending.
    *
    * The expected execution order is that all pending callbacks will
    * be fired first (and in the order that they were queued) and then the
    * Promise resolution handlers will all be invoked later on during the
    * next microtask checkpoint.
    *
+   * Using window.top.promiseDocumentFlushed in combination with a callback
+   * that is querying items in a window that might be swapped out via
+   * nsFrameLoader::SwapWithOtherLoader is highly discouraged. For example:
+   *
+   *   let result = await window.top.promiseDocumentFlushed(() => {
+   *     return window.document.body.getBoundingClientRect();
+   *   });
+   *
+   *   If "window" might get swapped out via nsFrameLoader::SwapWithOtherLoader
+   *   at any time, then the callback might get called when the new host window
+   *   will still incur layout flushes, since it's only the original host window
+   *   that's being monitored via window.top.promiseDocumentFlushed.
+   *
+   *   See bug 1519407 for further details.
+   *
    * promiseDocumentFlushed does not support re-entrancy - so calling it from
    * within a promiseDocumentFlushed callback will result in the inner call
    * throwing an NS_ERROR_FAILURE exception, and the outer Promise rejecting
    * with that exception.
    *
    * The callback function *must not make any changes which would require
    * a style or layout flush*.
    *