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
8interface nsIFile;
9interface nsICycleCollectorLogSink;
10
11[scriptable, function, uuid(2dea18fc-fbfa-4bf7-ad45-0efaf5495f5e)]
12interface 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)]
23interface 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)]
48interface 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};
168