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