1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/base/nsIMemoryInfoDumper.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,158 @@
1.4 +/* -*- Mode: C++; tab-width: 50; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +[scriptable, function, uuid(2dea18fc-fbfa-4bf7-ad45-0efaf5495f5e)]
1.12 +interface nsIFinishDumpingCallback : nsISupports
1.13 +{
1.14 + void callback(in nsISupports data);
1.15 +};
1.16 +
1.17 +[scriptable, builtinclass, uuid(815bf31b-f5bd-425d-85c3-4657a7a91dad)]
1.18 +interface nsIMemoryInfoDumper : nsISupports
1.19 +{
1.20 + /**
1.21 + * This dumps gzipped memory reports for this process and its child
1.22 + * processes. If a file of the given name exists, it will be overwritten.
1.23 + *
1.24 + * @param aFilename The output file.
1.25 + *
1.26 + * Sample output:
1.27 + *
1.28 + * {
1.29 + * "hasMozMallocUsableSize":true,
1.30 + * "reports": [
1.31 + * {"process":"Main Process (pid 12345)", "path":"explicit/foo/bar",
1.32 + * "kind":1, "units":0, "amount":2000000, "description":"Foo bar."},
1.33 + * {"process":"Main Process (pid 12345)", "path":"heap-allocated",
1.34 + * "kind":1, "units":0, "amount":3000000, "description":"Heap allocated."},
1.35 + * {"process":"Main Process (pid 12345)", "path":"vsize",
1.36 + * "kind":1, "units":0, "amount":10000000, "description":"Vsize."}
1.37 + * ]
1.38 + * }
1.39 + *
1.40 + * JSON schema for the output.
1.41 + *
1.42 + * {
1.43 + * "properties": {
1.44 + * "hasMozMallocUsableSize": {
1.45 + * "type": "boolean",
1.46 + * "description": "nsIMemoryReporterManager::hasMozMallocUsableSize",
1.47 + * "required": true
1.48 + * },
1.49 + * "reports": {
1.50 + * "type": "array",
1.51 + * "description": "The memory reports.",
1.52 + * "required": true
1.53 + * "minItems": 1,
1.54 + * "items": {
1.55 + * "type": "object",
1.56 + * "properties": {
1.57 + * "process": {
1.58 + * "type": "string",
1.59 + * "description": "nsIMemoryReporter::process",
1.60 + * "required": true
1.61 + * },
1.62 + * "path": {
1.63 + * "type": "string",
1.64 + * "description": "nsIMemoryReporter::path",
1.65 + * "required": true,
1.66 + * "minLength": 1
1.67 + * },
1.68 + * "kind": {
1.69 + * "type": "integer",
1.70 + * "description": "nsIMemoryReporter::kind",
1.71 + * "required": true
1.72 + * },
1.73 + * "units": {
1.74 + * "type": "integer",
1.75 + * "description": "nsIMemoryReporter::units",
1.76 + * "required": true
1.77 + * },
1.78 + * "amount": {
1.79 + * "type": "integer",
1.80 + * "description": "nsIMemoryReporter::amount",
1.81 + * "required": true
1.82 + * },
1.83 + * "description": {
1.84 + * "type": "string",
1.85 + * "description": "nsIMemoryReporter::description",
1.86 + * "required": true
1.87 + * }
1.88 + * }
1.89 + * }
1.90 + * }
1.91 + * }
1.92 + * }
1.93 + */
1.94 + void dumpMemoryReportsToNamedFile(in AString aFilename,
1.95 + in nsIFinishDumpingCallback aFinishDumping,
1.96 + in nsISupports aFinishDumpingData);
1.97 +
1.98 + /**
1.99 + * Similar to dumpMemoryReportsToNamedFile, this method dumps gzipped memory
1.100 + * reports for this process and its child processes to files in the tmp
1.101 + * directory called memory-reports-<identifier>-<pid>.json.gz (or something
1.102 + * similar, such as memory-reports-<identifier>-<pid>-1.json.gz; no existing
1.103 + * file will be overwritten).
1.104 + *
1.105 + * If DMD is enabled, this method also dumps gzipped DMD output to a file in
1.106 + * the tmp directory called dmd-<identifier>-<pid>.txt.gz (or something
1.107 + * similar; again, no existing file will be overwritten).
1.108 + *
1.109 + * @param aIdentifier this identifier will appear in the filename of our
1.110 + * about:memory dump and those of our children.
1.111 + *
1.112 + * If the identifier is empty, the implementation may set it arbitrarily
1.113 + * and use that new value for its own dump and the dumps of its child
1.114 + * processes. For example, the implementation may set |aIdentifier| to the
1.115 + * number of seconds since the epoch.
1.116 + *
1.117 + * @param aMinimizeMemoryUsage indicates whether we should run a series of
1.118 + * gc/cc's in an attempt to reduce our memory usage before collecting our
1.119 + * memory report.
1.120 + */
1.121 + void dumpMemoryInfoToTempDir(
1.122 + in AString aIdentifier,
1.123 + in bool aMinimizeMemoryUsage);
1.124 +
1.125 + /**
1.126 + * Dump GC and CC logs to files in the OS's temp directory (or in
1.127 + * $MOZ_CC_LOG_DIRECTORY, if that environment variable is specified).
1.128 + *
1.129 + * @param aIdentifier If aIdentifier is non-empty, this string will appear in
1.130 + * the filenames of the logs we create (both for this process and, if
1.131 + * aDumpChildProcesses is true, for our child processes).
1.132 + *
1.133 + * If aIdentifier is empty, the implementation may set it to an
1.134 + * arbitrary value; for example, it may set aIdentifier to the number
1.135 + * of seconds since the epoch.
1.136 + *
1.137 + * @param aDumpAllTraces indicates whether we should run an all-traces CC
1.138 + * log. An all-traces log visits all objects currently eligible for cycle
1.139 + * collection, while a non-all-traces log avoids visiting some objects
1.140 + * which we know are reachable.
1.141 + *
1.142 + * All-traces logs are much bigger than the alternative, but they may be
1.143 + * helpful when trying to understand why a particular object is alive. For
1.144 + * example, a non-traces-log will skip references held by an active
1.145 + * document; if your object is being held alive by such a document, you
1.146 + * probably want to see those references.
1.147 + *
1.148 + * @param aDumpChildProcesses indicates whether we should call
1.149 + * DumpGCAndCCLogsToFile in our child processes. If so, the child processes
1.150 + * will dump their children, and so on.
1.151 + *
1.152 + * @param aGCLogPath The full path of the file that the GC log was written to.
1.153 + *
1.154 + * @param aCCLogPath The full path of the file that the CC log was written to.
1.155 + */
1.156 + void dumpGCAndCCLogsToFile(in AString aIdentifier,
1.157 + in bool aDumpAllTraces,
1.158 + in bool aDumpChildProcesses,
1.159 + out AString aGCLogPath,
1.160 + out AString aCCLogPath);
1.161 +};
