xpcom/base/nsIMemoryInfoDumper.idl

   1 /* -*- Mode: C++; tab-width: 50; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIFile;
   9 interface nsICycleCollectorLogSink;
  10
  11 [scriptable, function, uuid(2dea18fc-fbfa-4bf7-ad45-0efaf5495f5e)]
  12 interface nsIFinishDumpingCallback : nsISupports
  13 {
  14   void callback(in nsISupports data);
  15 };
  16
  17 /**
  18  * Callback interface for |dumpGCAndCCLogsToFile|, below.  Note that
  19  * these method calls can occur before |dumpGCAndCCLogsToFile|
  20  * returns.
  21  */
  22 [scriptable, uuid(dc1b2b24-65bd-441b-b6bd-cb5825a7ed14)]
  23 interface nsIDumpGCAndCCLogsCallback : nsISupports
  24 {
  25   /**
  26    * Called whenever a process has successfully finished dumping its GC/CC logs.
  27    * Incomplete dumps (e.g., if the child crashes or is killed due to memory
  28    * exhaustion) are not reported.
  29    *
  30    * @param aGCLog The file that the GC log was written to.
  31    *
  32    * @param aCCLog The file that the CC log was written to.
  33    *
  34    * @param aIsParent indicates whether this log file pair is from the
  35    * parent process.
  36    */
  37   void onDump(in nsIFile aGCLog,
  38               in nsIFile aCCLog,
  39               in bool aIsParent);
  40
  41   /**
  42    * Called when GC/CC logging has finished, after all calls to |onDump|.
  43    */
  44   void onFinish();
  45 };
  46
  47 [scriptable, builtinclass, uuid(48541b74-47ee-4a62-9557-7f4b809bda5c)]
  48 interface nsIMemoryInfoDumper : nsISupports
  49 {
  50   /**
  51    * This dumps gzipped memory reports for this process and its child
  52    * processes.  If a file of the given name exists, it will be overwritten.
  53    *
  54    * @param aFilename The output file.
  55    *
  56    * @param aFinishDumping The callback called on completion.
  57    *
  58    * @param aFinishDumpingData The environment for the callback.
  59    *
  60    * @param aAnonymize Should the reports be anonymized?
  61    *
  62    * @param aMinimizeMemoryUsage indicates whether we should run a series of
  63    *   GC/CC's in an attempt to reduce our memory usage before collecting our
  64    *   memory report.
  65    *
  66    * Sample output, annotated with comments for explanatory purposes.
  67    *
  68    * {
  69    *   // The version number of the format, which will be incremented each time
  70    *   // backwards-incompatible changes are made. A mandatory integer.
  71    *   "version": 1
  72    *
  73    *   // Equal to nsIMemoryReporterManager::hasMozMallocUsableSize. A
  74    *   // mandatory boolean.
  75    *   "hasMozMallocUsableSize": true,
  76    *
  77    *   // The memory reports. A mandatory array.
  78    *   "reports": [
  79    *     // The properties correspond to the arguments of
  80    *     // nsIHandleReportCallback::callback. Every one is mandatory.
  81    *     {"process":"Main Process (pid 12345)", "path":"explicit/foo/bar",
  82    *      "kind":1, "units":0, "amount":2000000, "description":"Foo bar."},
  83    *     {"process":"Main Process (pid 12345)", "path":"heap-allocated",
  84    *      "kind":1, "units":0, "amount":3000000, "description":"Heap allocated."},
  85    *     {"process":"Main Process (pid 12345)", "path":"vsize",
  86    *      "kind":1, "units":0, "amount":10000000, "description":"Vsize."}
  87    *   ]
  88    * }
  89    */
  90   void dumpMemoryReportsToNamedFile(in AString aFilename,
  91                                     in nsIFinishDumpingCallback aFinishDumping,
  92                                     in nsISupports aFinishDumpingData,
  93                                     in boolean aAnonymize,
  94                                     in boolean aMinimizeMemoryUsage);
  95
  96   /**
  97    * Similar to dumpMemoryReportsToNamedFile, this method dumps gzipped memory
  98    * reports for this process and its child processes to files in the tmp
  99    * directory called memory-reports-<identifier>-<pid>.json.gz (or something
 100    * similar, such as memory-reports-<identifier>-<pid>-1.json.gz; no existing
 101    * file will be overwritten).
 102    *
 103    * If DMD is enabled, this method also dumps gzipped DMD output for this
 104    * process and its child processes to files in the tmp directory called
 105    * dmd-<identifier>-<pid>.txt.gz (or something similar; again, no existing
 106    * file will be overwritten).
 107    *
 108    * @param aIdentifier this identifier will appear in the filename of our
 109    *   about:memory dump and those of our children.
 110    *
 111    *   If the identifier is empty, the implementation may set it arbitrarily
 112    *   and use that new value for its own dump and the dumps of its child
 113    *   processes.  For example, the implementation may set |aIdentifier| to the
 114    *   number of seconds since the epoch.
 115    *
 116    * @param aAnonymize Should the reports be anonymized?
 117    *
 118    * @param aMinimizeMemoryUsage indicates whether we should run a series of
 119    *   GC/CC's in an attempt to reduce our memory usage before collecting our
 120    *   memory report.
 121    */
 122   void dumpMemoryInfoToTempDir(
 123     in AString aIdentifier,
 124     in boolean aAnonymize,
 125     in boolean aMinimizeMemoryUsage);
 126
 127   /**
 128    * Dump GC and CC logs to files in the OS's temp directory (or in
 129    * $MOZ_CC_LOG_DIRECTORY, if that environment variable is specified).
 130    *
 131    * @param aIdentifier If aIdentifier is non-empty, this string will appear in
 132    *   the filenames of the logs we create (both for this process and, if
 133    *   aDumpChildProcesses is true, for our child processes).
 134    *
 135    *   If aIdentifier is empty, the implementation may set it to an
 136    *   arbitrary value; for example, it may set aIdentifier to the number
 137    *   of seconds since the epoch.
 138    *
 139    * @param aDumpAllTraces indicates whether we should run an all-traces CC
 140    *   log.  An all-traces log visits all objects currently eligible for cycle
 141    *   collection, while a non-all-traces log avoids visiting some objects
 142    *   which we know are reachable.
 143    *
 144    *   All-traces logs are much bigger than the alternative, but they may be
 145    *   helpful when trying to understand why a particular object is alive.  For
 146    *   example, a non-traces-log will skip references held by an active
 147    *   document; if your object is being held alive by such a document, you
 148    *   probably want to see those references.
 149    *
 150    * @param aDumpChildProcesses indicates whether we should call
 151    *   DumpGCAndCCLogsToFile in our child processes.  If so, the child processes
 152    *   will dump their children, and so on.
 153    *
 154    */
 155   void dumpGCAndCCLogsToFile(in AString aIdentifier,
 156                              in bool aDumpAllTraces,
 157                              in bool aDumpChildProcesses,
 158                              in nsIDumpGCAndCCLogsCallback aCallback);
 159
 160   /**
 161    * Like |dumpGCAndCCLogsToFile|, but sends the logs to the given log
 162    * sink object instead of accessing the filesystem directly, and
 163    * dumps the current process only.
 164    */
 165   void dumpGCAndCCLogsToSink(in bool aDumpAllTraces,
 166                              in nsICycleCollectorLogSink aSink);
 167 };