/* -*- 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();
};