From cb75c6c34c5523ecb64dac4e30a789c7ad6e91c2 Mon Sep 17 00:00:00 2001
From: Nick Fitzgerald <fitzgen@gmail.com>
Date: Thu, 28 May 2015 07:37:42 -0700
Subject: [PATCH] Bug 1024774 - Part 1: Add the ChromeUtils WebIDL interface.
 r=bholley

---
 dom/bindings/Bindings.conf    |  8 +++++
 dom/webidl/ChromeUtils.webidl | 55 +++++++++++++++++++++++++++++++++++
 dom/webidl/moz.build          |  1 +
 3 files changed, 64 insertions(+)
 create mode 100644 dom/webidl/ChromeUtils.webidl

diff --git a/dom/bindings/Bindings.conf b/dom/bindings/Bindings.conf
index ce8ffef4caa9..3b7505625130 100644
--- a/dom/bindings/Bindings.conf
+++ b/dom/bindings/Bindings.conf
@@ -266,6 +266,14 @@ DOMInterfaces = {
     'concrete': False
 },
 
+'ChromeUtils': {
+    # The codegen is dumb, and doesn't understand that this interface is only a
+    # collection of static methods, so we have this `concrete: False` hack.
+    'concrete': False,
+    'nativeType': 'mozilla::devtools::ChromeUtils',
+    'implicitJSContext': ['saveHeapSnapshot']
+},
+
 'ChromeWindow': {
     'concrete': False,
 },
diff --git a/dom/webidl/ChromeUtils.webidl b/dom/webidl/ChromeUtils.webidl
new file mode 100644
index 000000000000..43ab2b7dd9f4
--- /dev/null
+++ b/dom/webidl/ChromeUtils.webidl
@@ -0,0 +1,55 @@
+/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* 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/.
+ */
+
+/**
+ * A collection of static utility methods that are only exposed to Chrome.
+ */
+[ChromeOnly, Exposed=(Window,System)]
+interface ChromeUtils {
+  /**
+   * Serialize a snapshot of the heap graph, as seen by |JS::ubi::Node| and
+   * restricted by |boundaries|, and write it to the provided file path.
+   *
+   * @param filePath          The file path to write the heap snapshot to.
+   *
+   * @param boundaries        The portion of the heap graph to write.
+   */
+  [Throws]
+  static void saveHeapSnapshot(DOMString filePath,
+                               optional HeapSnapshotBoundaries boundaries);
+};
+
+/**
+ * A JS object whose properties specify what portion of the heap graph to
+ * write. The recognized properties are:
+ *
+ * * globals: [ global, ... ]
+ *   Dump only nodes that either:
+ *   - belong in the compartment of one of the given globals;
+ *   - belong to no compartment, but do belong to a Zone that contains one of
+ *     the given globals;
+ *   - are referred to directly by one of the last two kinds of nodes; or
+ *   - is the fictional root node, described below.
+ *
+ * * debugger: Debugger object
+ *   Like "globals", but use the Debugger's debuggees as the globals.
+ *
+ * * runtime: true
+ *   Dump the entire heap graph, starting with the JSRuntime's roots.
+ *
+ * One, and only one, of these properties must exist on the boundaries object.
+ *
+ * The root of the dumped graph is a fictional node whose ubi::Node type name is
+ * "CoreDumpRoot". If we are dumping the entire ubi::Node graph, this root node
+ * has an edge for each of the JSRuntime's roots. If we are dumping a selected
+ * set of globals, the root has an edge to each global, and an edge for each
+ * incoming JS reference to the selected Zones.
+ */
+dictionary HeapSnapshotBoundaries {
+  sequence<object> globals;
+  object           debugger;
+  boolean          runtime;
+};
diff --git a/dom/webidl/moz.build b/dom/webidl/moz.build
index a53e50c862c5..25e64bb765e0 100644
--- a/dom/webidl/moz.build
+++ b/dom/webidl/moz.build
@@ -74,6 +74,7 @@ WEBIDL_FILES = [
     'CharacterData.webidl',
     'ChildNode.webidl',
     'ChromeNotifications.webidl',
+    'ChromeUtils.webidl',
     'Client.webidl',
     'Clients.webidl',
     'ClipboardEvent.webidl',