1 files changed, 516 insertions, 0 deletions
diff --git a/devtools/server/actors/reflow.js b/devtools/server/actors/reflow.js
new file mode 100644
index 0000000000..3eda67cc8c
--- /dev/null
+++ b/devtools/server/actors/reflow.js
@@ -0,0 +1,516 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+/**
+ * About the types of objects in this file:
+ *
+ * - ReflowActor: the actor class used for protocol purposes.
+ *   Mostly empty, just gets an instance of LayoutChangesObserver and forwards
+ *   its "reflows" events to clients.
+ *
+ * - LayoutChangesObserver: extends Observable and uses the ReflowObserver, to
+ *   track reflows on the page.
+ *   Used by the LayoutActor, but is also exported on the module, so can be used
+ *   by any other actor that needs it.
+ *
+ * - Observable: A utility parent class, meant at being extended by classes that
+ *   need a to observe something on the targetActor's windows.
+ *
+ * - Dedicated observers: There's only one of them for now: ReflowObserver which
+ *   listens to reflow events via the docshell,
+ *   These dedicated classes are used by the LayoutChangesObserver.
+ */
+
+const { Actor } = require("resource://devtools/shared/protocol.js");
+const { reflowSpec } = require("resource://devtools/shared/specs/reflow.js");
+
+const EventEmitter = require("resource://devtools/shared/event-emitter.js");
+
+/**
+ * The reflow actor tracks reflows and emits events about them.
+ */
+exports.ReflowActor = class ReflowActor extends Actor {
+  constructor(conn, targetActor) {
+    super(conn, reflowSpec);
+
+    this.targetActor = targetActor;
+    this._onReflow = this._onReflow.bind(this);
+    this.observer = getLayoutChangesObserver(targetActor);
+    this._isStarted = false;
+  }
+
+  destroy() {
+    this.stop();
+    releaseLayoutChangesObserver(this.targetActor);
+    this.observer = null;
+    this.targetActor = null;
+
+    super.destroy();
+  }
+
+  /**
+   * Start tracking reflows and sending events to clients about them.
+   * This is a oneway method, do not expect a response and it won't return a
+   * promise.
+   */
+  start() {
+    if (!this._isStarted) {
+      this.observer.on("reflows", this._onReflow);
+      this._isStarted = true;
+    }
+  }
+
+  /**
+   * Stop tracking reflows and sending events to clients about them.
+   * This is a oneway method, do not expect a response and it won't return a
+   * promise.
+   */
+  stop() {
+    if (this._isStarted) {
+      this.observer.off("reflows", this._onReflow);
+      this._isStarted = false;
+    }
+  }
+
+  _onReflow(reflows) {
+    if (this._isStarted) {
+      this.emit("reflows", reflows);
+    }
+  }
+};
+
+/**
+ * Base class for all sorts of observers that need to listen to events on the
+ * targetActor's windows.
+ * @param {WindowGlobalTargetActor} targetActor
+ * @param {Function} callback Executed everytime the observer observes something
+ */
+class Observable {
+  constructor(targetActor, callback) {
+    this.targetActor = targetActor;
+    this.callback = callback;
+
+    this._onWindowReady = this._onWindowReady.bind(this);
+    this._onWindowDestroyed = this._onWindowDestroyed.bind(this);
+
+    this.targetActor.on("window-ready", this._onWindowReady);
+    this.targetActor.on("window-destroyed", this._onWindowDestroyed);
+  }
+
+  /**
+   * Is the observer currently observing
+   */
+  isObserving = false;
+
+  /**
+   * Stop observing and detroy this observer instance
+   */
+  destroy() {
+    if (this.isDestroyed) {
+      return;
+    }
+    this.isDestroyed = true;
+
+    this.stop();
+
+    this.targetActor.off("window-ready", this._onWindowReady);
+    this.targetActor.off("window-destroyed", this._onWindowDestroyed);
+
+    this.callback = null;
+    this.targetActor = null;
+  }
+
+  /**
+   * Start observing whatever it is this observer is supposed to observe
+   */
+  start() {
+    if (this.isObserving) {
+      return;
+    }
+    this.isObserving = true;
+
+    this._startListeners(this.targetActor.windows);
+  }
+
+  /**
+   * Stop observing
+   */
+  stop() {
+    if (!this.isObserving) {
+      return;
+    }
+    this.isObserving = false;
+
+    if (!this.targetActor.isDestroyed() && this.targetActor.docShell) {
+      // It's only worth stopping if the targetActor is still active
+      this._stopListeners(this.targetActor.windows);
+    }
+  }
+
+  _onWindowReady({ window }) {
+    if (this.isObserving) {
+      this._startListeners([window]);
+    }
+  }
+
+  _onWindowDestroyed({ window }) {
+    if (this.isObserving) {
+      this._stopListeners([window]);
+    }
+  }
+
+  _startListeners(windows) {
+    // To be implemented by sub-classes.
+  }
+
+  _stopListeners(windows) {
+    // To be implemented by sub-classes.
+  }
+
+  /**
+   * To be called by sub-classes when something has been observed
+   */
+  notifyCallback(...args) {
+    this.isObserving && this.callback && this.callback.apply(null, args);
+  }
+}
+
+/**
+ * The LayouChangesObserver will observe reflows as soon as it is started.
+ * Some devtools actors may cause reflows and it may be wanted to "hide" these
+ * reflows from the LayouChangesObserver consumers.
+ * If this is the case, such actors should require this module and use this
+ * global function to turn the ignore mode on and off temporarily.
+ *
+ * Note that if a node is provided, it will be used to force a sync reflow to
+ * make sure all reflows which occurred before switching the mode on or off are
+ * either observed or ignored depending on the current mode.
+ *
+ * @param {Boolean} ignore
+ * @param {DOMNode} syncReflowNode The node to use to force a sync reflow
+ */
+var gIgnoreLayoutChanges = false;
+exports.setIgnoreLayoutChanges = function (ignore, syncReflowNode) {
+  if (syncReflowNode) {
+    let forceSyncReflow = syncReflowNode.offsetWidth; // eslint-disable-line
+  }
+  gIgnoreLayoutChanges = ignore;
+};
+
+class LayoutChangesObserver extends EventEmitter {
+  /**
+   * The LayoutChangesObserver class is instantiated only once per given tab
+   * and is used to track reflows and dom and style changes in that tab.
+   * The LayoutActor uses this class to send reflow events to its clients.
+   *
+   * This class isn't exported on the module because it shouldn't be instantiated
+   * to avoid creating several instances per tabs.
+   * Use `getLayoutChangesObserver(targetActor)`
+   * and `releaseLayoutChangesObserver(targetActor)`
+   * which are exported to get and release instances.
+   *
+   * The observer loops every EVENT_BATCHING_DELAY ms and checks if layout changes
+   * have happened since the last loop iteration. If there are, it sends the
+   * corresponding events:
+   *
+   * - "reflows", with an array of all the reflows that occured,
+   * - "resizes", with an array of all the resizes that occured,
+   *
+   * @param {WindowGlobalTargetActor} targetActor
+   */
+  constructor(targetActor) {
+    super();
+
+    this.targetActor = targetActor;
+
+    this._startEventLoop = this._startEventLoop.bind(this);
+    this._onReflow = this._onReflow.bind(this);
+    this._onResize = this._onResize.bind(this);
+
+    // Creating the various observers we're going to need
+    // For now, just the reflow observer, but later we can add markupMutation,
+    // styleSheetChanges and styleRuleChanges
+    this.reflowObserver = new ReflowObserver(this.targetActor, this._onReflow);
+    this.resizeObserver = new WindowResizeObserver(
+      this.targetActor,
+      this._onResize
+    );
+  }
+
+  /**
+   * How long does this observer waits before emitting batched events.
+   * The lower the value, the more event packets will be sent to clients,
+   * potentially impacting performance.
+   * The higher the value, the more time we'll wait, this is better for
+   * performance but has an effect on how soon changes are shown in the toolbox.
+   */
+  EVENT_BATCHING_DELAY = 300;
+
+  /**
+   * Destroying this instance of LayoutChangesObserver will stop the batched
+   * events from being sent.
+   */
+  destroy() {
+    this.isObserving = false;
+
+    this.reflowObserver.destroy();
+    this.reflows = null;
+
+    this.resizeObserver.destroy();
+    this.hasResized = false;
+
+    this.targetActor = null;
+  }
+
+  start() {
+    if (this.isObserving) {
+      return;
+    }
+    this.isObserving = true;
+
+    this.reflows = [];
+    this.hasResized = false;
+
+    this._startEventLoop();
+
+    this.reflowObserver.start();
+    this.resizeObserver.start();
+  }
+
+  stop() {
+    if (!this.isObserving) {
+      return;
+    }
+    this.isObserving = false;
+
+    this._stopEventLoop();
+
+    this.reflows = [];
+    this.hasResized = false;
+
+    this.reflowObserver.stop();
+    this.resizeObserver.stop();
+  }
+
+  /**
+   * Start the event loop, which regularly checks if there are any observer
+   * events to be sent as batched events
+   * Calls itself in a loop.
+   */
+  _startEventLoop() {
+    // Avoid emitting events if the targetActor has been detached (may happen
+    // during shutdown)
+    if (!this.targetActor || this.targetActor.isDestroyed()) {
+      return;
+    }
+
+    // Send any reflows we have
+    if (this.reflows && this.reflows.length) {
+      this.emit("reflows", this.reflows);
+      this.reflows = [];
+    }
+
+    // Send any resizes we have
+    if (this.hasResized) {
+      this.emit("resize");
+      this.hasResized = false;
+    }
+
+    this.eventLoopTimer = this._setTimeout(
+      this._startEventLoop,
+      this.EVENT_BATCHING_DELAY
+    );
+  }
+
+  _stopEventLoop() {
+    this._clearTimeout(this.eventLoopTimer);
+  }
+
+  // Exposing set/clearTimeout here to let tests override them if needed
+  _setTimeout(cb, ms) {
+    return setTimeout(cb, ms);
+  }
+  _clearTimeout(t) {
+    return clearTimeout(t);
+  }
+
+  /**
+   * Executed whenever a reflow is observed. Only stacks the reflow in the
+   * reflows array.
+   * The EVENT_BATCHING_DELAY loop will take care of it later.
+   * @param {Number} start When the reflow started
+   * @param {Number} end When the reflow ended
+   * @param {Boolean} isInterruptible
+   */
+  _onReflow(start, end, isInterruptible) {
+    if (gIgnoreLayoutChanges) {
+      return;
+    }
+
+    // XXX: when/if bug 997092 gets fixed, we will be able to know which
+    // elements have been reflowed, which would be a nice thing to add here.
+    this.reflows.push({
+      start,
+      end,
+      isInterruptible,
+    });
+  }
+
+  /**
+   * Executed whenever a resize is observed. Only store a flag saying that a
+   * resize occured.
+   * The EVENT_BATCHING_DELAY loop will take care of it later.
+   */
+  _onResize() {
+    if (gIgnoreLayoutChanges) {
+      return;
+    }
+
+    this.hasResized = true;
+  }
+}
+exports.LayoutChangesObserver = LayoutChangesObserver;
+
+/**
+ * Get a LayoutChangesObserver instance for a given window. This function makes
+ * sure there is only one instance per window.
+ * @param {WindowGlobalTargetActor} targetActor
+ * @return {LayoutChangesObserver}
+ */
+var observedWindows = new Map();
+function getLayoutChangesObserver(targetActor) {
+  const observerData = observedWindows.get(targetActor);
+  if (observerData) {
+    observerData.refCounting++;
+    return observerData.observer;
+  }
+
+  const obs = new LayoutChangesObserver(targetActor);
+  observedWindows.set(targetActor, {
+    observer: obs,
+    // counting references allows to stop the observer when no targetActor owns an
+    // instance.
+    refCounting: 1,
+  });
+  obs.start();
+  return obs;
+}
+exports.getLayoutChangesObserver = getLayoutChangesObserver;
+
+/**
+ * Release a LayoutChangesObserver instance that was retrieved by
+ * getLayoutChangesObserver. This is required to ensure the targetActor reference
+ * is removed and the observer is eventually stopped and destroyed.
+ * @param {WindowGlobalTargetActor} targetActor
+ */
+function releaseLayoutChangesObserver(targetActor) {
+  const observerData = observedWindows.get(targetActor);
+  if (!observerData) {
+    return;
+  }
+
+  observerData.refCounting--;
+  if (!observerData.refCounting) {
+    observerData.observer.destroy();
+    observedWindows.delete(targetActor);
+  }
+}
+exports.releaseLayoutChangesObserver = releaseLayoutChangesObserver;
+
+/**
+ * Reports any reflow that occurs in the targetActor's docshells.
+ * @extends Observable
+ * @param {WindowGlobalTargetActor} targetActor
+ * @param {Function} callback Executed everytime a reflow occurs
+ */
+class ReflowObserver extends Observable {
+  constructor(targetActor, callback) {
+    super(targetActor, callback);
+  }
+
+  _startListeners(windows) {
+    for (const window of windows) {
+      window.docShell.addWeakReflowObserver(this);
+    }
+  }
+
+  _stopListeners(windows) {
+    for (const window of windows) {
+      try {
+        window.docShell.removeWeakReflowObserver(this);
+      } catch (e) {
+        // Corner cases where a global has already been freed may happen, in
+        // which case, no need to remove the observer.
+      }
+    }
+  }
+
+  reflow(start, end) {
+    this.notifyCallback(start, end, false);
+  }
+
+  reflowInterruptible(start, end) {
+    this.notifyCallback(start, end, true);
+  }
+}
+
+ReflowObserver.prototype.QueryInterface = ChromeUtils.generateQI([
+  "nsIReflowObserver",
+  "nsISupportsWeakReference",
+]);
+
+/**
+ * Reports window resize events on the targetActor's windows.
+ * @extends Observable
+ * @param {WindowGlobalTargetActor} targetActor
+ * @param {Function} callback Executed everytime a resize occurs
+ */
+class WindowResizeObserver extends Observable {
+  constructor(targetActor, callback) {
+    super(targetActor, callback);
+
+    this.onNavigate = this.onNavigate.bind(this);
+    this.onResize = this.onResize.bind(this);
+
+    this.targetActor.on("navigate", this.onNavigate);
+  }
+
+  _startListeners() {
+    this.listenerTarget.addEventListener("resize", this.onResize);
+  }
+
+  _stopListeners() {
+    this.listenerTarget.removeEventListener("resize", this.onResize);
+  }
+
+  onNavigate() {
+    if (this.isObserving) {
+      this._stopListeners();
+      this._startListeners();
+    }
+  }
+
+  onResize() {
+    this.notifyCallback();
+  }
+
+  destroy() {
+    if (this.targetActor) {
+      this.targetActor.off("navigate", this.onNavigate);
+    }
+    super.destroy();
+  }
+
+  get listenerTarget() {
+    // For the rootActor, return its window.
+    if (this.targetActor.isRootActor) {
+      return this.targetActor.window;
+    }
+
+    // Otherwise, get the targetActor's chromeEventHandler.
+    return this.targetActor.chromeEventHandler;
+  }
+}