1 files changed, 72 insertions, 0 deletions
diff --git a/tools/memory-profiler/nsIMemoryProfiler.idl b/tools/memory-profiler/nsIMemoryProfiler.idl
new file mode 100644
index 000000000..4ca386f9d
--- /dev/null
+++ b/tools/memory-profiler/nsIMemoryProfiler.idl
@@ -0,0 +1,72 @@
+/* -*- 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/. */
+
+#include "nsISupports.idl"
+
+/**
+ * The memory profiler samples allocation events. An allocation event
+ * includes a type (what and at where is going to be allocated), a
+ * size, a timestamp and the corresponding stack trace. Free events
+ * are also tracked. For managed languages, namely languages relying
+ * on garbage collection, a free event is generated when an object is
+ * reclaimed by the garbage collector.  These sampled events can be
+ * used to approximate the full history of allocations afterwards.
+ * That means we can get various memory profiles of a program in
+ * different perspectives by post-processing the history in different
+ * ways. The profiler is designed at the very beginning to support not
+ * only JavaScript but also native codes. Naturally, not only
+ * JavaScript objects but also native allocations are tracked.
+ *
+ * The result returned is the sampled allocation event traces in a
+ * compact format. The events is sorted according to the timestamp
+ * when the event happened. Each event has a trace index pointing to
+ * the traces table. Each trace entry has a name index pointing to the
+ * names table and a parent index pointing to the parent trace in the
+ * traces table. By following the trace index one could rebuild the
+ * complete backtrace of an allocation event.
+ *
+ *    [ Events ]
+ *    +-------+-------+      +-------+
+ *    | Size  | Size  |      | Size  |
+ *    |-------|-------|      |-------|
+ *    | Time  | Time  |......| Time  |
+ *    |-------|-------|      |-------|
+ *  +-- Trace | Trace |      | Trace |
+ *  | +-------+-------+      +-------+
+ *  |
+ *  | [ Traces ]
+ *  +->--------+--------+   +--------+   +--------+
+ *   -| Name   | Name   |   | Name   |   | Name   |
+ *  / |--------|--------|...|--------|...|--------|
+ *  | | Parent | Parent |   | Parent |   | Parent |
+ *  | +---|----+----^--++   +--^--|--+   +---^----+
+ *  |     |         |  |       |  |          |
+ *  |     +---------+  +-------+  +----------+
+ *  | [ Names ]
+ *  | +-----------------+-----------------+
+ *  +-> Function name   | Function name   |
+ *    |  & line numbers |  & line numbers |......
+ *    +-----------------+-----------------+
+ *
+ */
+[scriptable, uuid(1e10e7a9-bc05-4878-a687-36c9ea4428b1)]
+interface nsIMemoryProfiler : nsISupports
+{
+  void startProfiler();
+  void stopProfiler();
+  void resetProfiler();
+
+  /**
+   * Get results in an object which contains three tables:
+   * {
+   *  names, // an array of function names and positions
+   *  traces, // an array of {nameIdx, parentIdx}
+   *  events, // an array of {size, timestamp, traceIdx}
+   * }
+   * Should only be called after stopProfiler.
+   */
+  [implicit_jscontext]
+  jsval getResults();
+};