DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (a81015259a98)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309
/* -*- Mode: C++; tab-width: 50; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * mozilla.org
 * Portions created by the Initial Developer are Copyright (C) 2008
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Vladimir Vukicevic <vladimir@pobox.com> (original author)
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

interface nsISimpleEnumerator;

/*
 * An nsIMemoryReporter reports a single memory measurement as an object.
 * Use this when it makes sense to gather this measurement without gathering
 * related measurements at the same time.
 *
 * Note that the |amount| field may be implemented as a function, and so
 * accessing it can trigger significant computation;  the other fields can
 * be accessed without triggering this computation.  (Compare and contrast
 * this with nsIMemoryMultiReporter.)  
 */
[scriptable, uuid(b2c39f65-1799-4b92-a806-ab3cf6af3cfa)]
interface nsIMemoryReporter : nsISupports
{
  /*
   * The name of the process containing this reporter.  Each reporter initially
   * has "" in this field, indicating that it applies to the current process.
   * (This is true even for reporters in a child process.)  When a reporter
   * from a child process is copied into the main process, the copy has its
   * 'process' field set appropriately.
   */
  readonly attribute ACString process;

  /*
   * The path that this memory usage should be reported under.  Paths are
   * '/'-delimited, eg. "a/b/c".  There are three categories of paths.
   *
   * - Paths starting with "explicit" represent regions of memory that have
   *   been explicitly allocated with an OS-level allocation (eg.
   *   mmap/VirtualAlloc/vm_allocate) or a heap-level allocation (eg.
   *   malloc/calloc/operator new).
   *
   *   Each reporter can be viewed as representing a node in a tree rooted at
   *   "explicit".  Not all nodes of the tree need have an associated reporter.
   *   So, for example, the reporters "explicit/a/b", "explicit/a/c",
   *   "explicit/d", "explicit/d/e", and "explicit/d/f" define this tree:
   *
   *     explicit
   *     |--a
   *     |  |--b [*]
   *     |  \--c [*]
   *     \--d [*]
   *        |--e [*]
   *        \--f [*]
   *
   *   Nodes marked with a [*] have a reporter.  Notice that "explicit/a" is
   *   implicitly defined.
   *
   *   A node's children divide their parent's memory into disjoint pieces.
   *   So in the example above, |a| may not count any allocations counted by
   *   |d|, and vice versa.
   *
   * - Paths starting with "map" represent regions of virtual memory that the
   *   process has mapped.  The reporter immediately beneath "map" describes
   *   the type of measurement; for instance, the reporter "map/rss/[stack]"
   *   might report how much of the process's stack is currently in physical
   *   memory.
   *
   *   Reporters in this category must have kind NONHEAP and units BYTES.
   *
   * - All other paths represent cross-cutting values and may overlap with any
   *   other reporter.
   */
  readonly attribute AUTF8String path;

  /*
   * There are three categories of memory reporters:
   *
   *  - HEAP: memory allocated by the heap allocator, e.g. by calling malloc,
   *    calloc, realloc, memalign, operator new, or operator new[].  Reporters
   *    in this category must have units UNITS_BYTES and must have a path
   *    starting with "explicit".

   *  - NONHEAP: memory which the program explicitly allocated, but does not
   *    live on the heap.  Such memory is commonly allocated by calling one of
   *    the OS's memory-mapping functions (e.g. mmap, VirtualAlloc, or
   *    vm_allocate).  Reporters in this category must have units UNITS_BYTES
   *    and must have a path starting with "explicit" or "map".
   *
   *  - OTHER: reporters which don't fit into either of these categories. Such
   *    reporters must have a path that does not start with "explicit" or "map"
   *    and may have any units.
   */
  const PRInt32 KIND_NONHEAP = 0;
  const PRInt32 KIND_HEAP    = 1;
  const PRInt32 KIND_OTHER   = 2;

  /*
   * KIND_MAPPED is a deprecated synonym for KIND_NONHEAP.  We keep it around
   * to as not to break extensions which might use this interface, but we will
   * remove it eventually.
   */
  const PRInt32 KIND_MAPPED  = 0;

  /*
   * The reporter kind.  See KIND_* above.
   */
  readonly attribute PRInt32 kind;

  /*
   * The amount reported by a memory reporter must have one of the following
   * units, but you may of course add new units as necessary:
   *
   *  - BYTES: The amount contains a number of bytes.
   *
   *  - COUNT: The amount is an instantaneous count of things currently in
   *    existence.  For instance, the number of tabs currently open would have
   *    units COUNT.
   *
   *  - COUNT_CUMULATIVE: The amount contains the number of times some event
   *    has occurred since the application started up.  For instance, the
   *    number of times the user has opened a new tab would have units
   *    COUNT_CUMULATIVE.
   *
   *    The amount returned by a reporter with units COUNT_CUMULATIVE must
   *    never decrease over the lifetime of the application.
   *
   *  - PERCENTAGE: The amount contains a fraction that should be expressed as
   *    a percentage.  NOTE!  The |amount| field should be given a value 100x
   *    the actual percentage;  this number will be divided by 100 when shown.
   *    This allows a fractional percentage to be shown even though |amount| is
   *    an integer.  E.g. if the actual percentage is 12.34%, |amount| should
   *    be 1234.
   */
  const PRInt32 UNITS_BYTES = 0;
  const PRInt32 UNITS_COUNT = 1;
  const PRInt32 UNITS_COUNT_CUMULATIVE = 2;
  const PRInt32 UNITS_PERCENTAGE = 3;

  /*
   * The units on the reporter's amount.  See UNITS_* above.
   */
  readonly attribute PRInt32 units;

  /*
   * The numeric value reported by this memory reporter.  -1 means "unknown",
   * ie. something went wrong when getting the amount.
   */
  readonly attribute PRInt64 amount;

  /*
   * A human-readable description of this memory usage report.
   */
  readonly attribute AUTF8String description;
};

[scriptable, function, uuid(5b15f3fa-ba15-443c-8337-7770f5f0ce5d)]
interface nsIMemoryMultiReporterCallback : nsISupports
{
  void callback(in ACString process, in AUTF8String path, in PRInt32 kind,
                in PRInt32 units, in PRInt64 amount,
                in AUTF8String description, in nsISupports closure);
};

/*
 * An nsIMemoryMultiReporter reports multiple memory measurements via a
 * callback function which is called once for each measurement.  Use this
 * when you want to gather multiple measurements in a single operation (eg.
 * a single traversal of a large data structure).
 *
 * The arguments to the callback deliberately match the fields in
 * nsIMemoryReporter, but note that seeing any of these arguments requires
 * calling collectReports which will trigger all relevant computation.
 * (Compare and contrast this with nsIMemoryReporter, which allows all
 * fields except |amount| to be accessed without triggering computation.)
 */
[scriptable, uuid(eae277ad-b67d-4389-95f4-03fa11c09d06)]
interface nsIMemoryMultiReporter : nsISupports
{
  void collectReports(in nsIMemoryMultiReporterCallback callback,
                      in nsISupports closure);
};

[scriptable, uuid(84ba9c85-3372-4423-b7ab-74708b9269a6)]
interface nsIMemoryReporterManager : nsISupports
{
  /*
   * Return an enumerator of nsIMemoryReporters that are currently registered.
   */
  nsISimpleEnumerator enumerateReporters ();

  /*
   * Return an enumerator of nsIMemoryMultiReporters that are currently
   * registered.
   */
  nsISimpleEnumerator enumerateMultiReporters ();

  /*
   * Register the given nsIMemoryReporter.  After a reporter is registered,
   * it will be available via enumerateReporters().  The Manager service
   * will hold a strong reference to the given reporter.
   */
  void registerReporter (in nsIMemoryReporter reporter);

  /*
   * Register the given nsIMemoryMultiReporter.  After a multi-reporter is
   * registered, it will be available via enumerateMultiReporters().  The
   * Manager service will hold a strong reference to the given
   * multi-reporter.
   */
  void registerMultiReporter (in nsIMemoryMultiReporter reporter);

  /*
   * Unregister the given memory reporter.
   */
  void unregisterReporter (in nsIMemoryReporter reporter);

  /*
   * Unregister the given memory multi-reporter.
   */
  void unregisterMultiReporter (in nsIMemoryMultiReporter reporter);

  /*
   * Initialize.
   */
  void init ();

  /*
   * Get the resident size (aka. RSS, physical memory used).  This reporter
   * is special-cased because it's interesting, is available on all
   * platforms, and returns a meaningful result on all common platforms.
   * -1 means unknown.
   */
  readonly attribute PRInt64 resident;

  /*
   * Get the total size of explicit memory allocations, both at the OS-level
   * (eg. via mmap, VirtualAlloc) and at the heap level (eg. via malloc,
   * calloc, operator new).  (Nb: it covers all heap allocations, but will
   * miss any OS-level ones not covered by memory reporters.)  This reporter
   * is special-cased because it's interesting, and is moderately difficult
   * to compute in JS.  -1 means unknown.
   */
  readonly attribute PRInt64 explicit;
};

%{C++

/*
 * Note that this defaults 'process' to "", which is usually what's desired.
 */
#define NS_MEMORY_REPORTER_IMPLEMENT_HELPER(_classname, _path, _kind, _units, _amountFunction, _desc, _ts) \
    class MemoryReporter_##_classname : public nsIMemoryReporter {                            \
    public:                                                                                   \
      NS_DECL_ISUPPORTS                                                                       \
      NS_IMETHOD GetProcess(nsACString &process) { process.Truncate(); return NS_OK; } \
      NS_IMETHOD GetPath(nsACString &memoryPath) { memoryPath.Assign(_path); return NS_OK; } \
      NS_IMETHOD GetKind(int *kind) { *kind = _kind; return NS_OK; }                          \
      NS_IMETHOD GetUnits(int *units) { *units = _units; return NS_OK; }                      \
      NS_IMETHOD GetAmount(PRInt64 *amount) { *amount = _amountFunction(); return NS_OK; }     \
      NS_IMETHOD GetDescription(nsACString &desc) { desc.Assign(_desc); return NS_OK; } \
    };                                                                                        \
    NS_IMPL##_ts##ISUPPORTS1(MemoryReporter_##_classname, nsIMemoryReporter)

#define NS_MEMORY_REPORTER_IMPLEMENT(_c, _p, _k, _u, _a, _d) \
        NS_MEMORY_REPORTER_IMPLEMENT_HELPER(_c, _p, _k, _u, _a, _d, _)
#define NS_THREADSAFE_MEMORY_REPORTER_IMPLEMENT(_c, _p, _k, _u, _a, _d) \
        NS_MEMORY_REPORTER_IMPLEMENT_HELPER(_c, _p, _k, _u, _a, _d, _THREADSAFE_)

#define NS_MEMORY_REPORTER_NAME(_classname)  MemoryReporter_##_classname

nsresult NS_RegisterMemoryReporter (nsIMemoryReporter *reporter);
nsresult NS_RegisterMemoryMultiReporter (nsIMemoryMultiReporter *reporter);

nsresult NS_UnregisterMemoryReporter (nsIMemoryReporter *reporter);
nsresult NS_UnregisterMemoryMultiReporter (nsIMemoryMultiReporter *reporter);

%}