gecko-dev/xpcom/base/nsIMemoryInfoDumper.idl
Justin Lebar b1b83ab016 Bug 890135 - Switch B2G's "gc log" dumping to produce all-traces logs by default. r=mccr8
This patch also adds "abbreviated gc log", which produces a not-all-traces CC log.

--HG--
extra : rebase_source : 84eed72c34b7cc8116fbe05258f5de22bf3275bc
2013-07-08 13:20:39 -04:00

153 lines
5.9 KiB
Plaintext

/* -*- Mode: C++; tab-width: 50; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
[scriptable, builtinclass, uuid(3FFA5113-2A10-43BB-923B-6A2FAF67BE97)]
interface nsIMemoryInfoDumper : nsISupports
{
/**
* This dumps gzipped memory reports for this process. If a file of the
* given name exists, it will be overwritten. Nothing is done for any child
* processes (and their children, recursively).
*
* @param aFilename The output file.
*
* Sample output:
*
* {
* "hasMozMallocUsableSize":true,
* "reports": [
* {"process":"Main Process (pid 12345)", "path":"explicit/foo/bar",
* "kind":1, "units":0, "amount":2000000, "description":"Foo bar."},
* {"process":"Main Process (pid 12345)", "path":"heap-allocated",
* "kind":1, "units":0, "amount":3000000, "description":"Heap allocated."},
* {"process":"Main Process (pid 12345)", "path":"vsize",
* "kind":1, "units":0, "amount":10000000, "description":"Vsize."}
* ]
* }
*
* JSON schema for the output.
*
* {
* "properties": {
* "hasMozMallocUsableSize": {
* "type": "boolean",
* "description": "nsIMemoryReporterManager::hasMozMallocUsableSize",
* "required": true
* },
* "reports": {
* "type": "array",
* "description": "The memory reports.",
* "required": true
* "minItems": 1,
* "items": {
* "type": "object",
* "properties": {
* "process": {
* "type": "string",
* "description": "nsIMemoryReporter::process",
* "required": true
* },
* "path": {
* "type": "string",
* "description": "nsIMemoryReporter::path",
* "required": true,
* "minLength": 1
* },
* "kind": {
* "type": "integer",
* "description": "nsIMemoryReporter::kind",
* "required": true
* },
* "units": {
* "type": "integer",
* "description": "nsIMemoryReporter::units",
* "required": true
* },
* "amount": {
* "type": "integer",
* "description": "nsIMemoryReporter::amount",
* "required": true
* },
* "description": {
* "type": "string",
* "description": "nsIMemoryReporter::description",
* "required": true
* }
* }
* }
* }
* }
* }
*/
void dumpMemoryReportsToNamedFile(in AString aFilename);
/**
* Similar to dumpMemoryReportsToNamedFile, this method dumps gzipped memory
* reports for this process and possibly our child processes (and their
* children, recursively) to a file in the tmp directory called
* memory-reports-<identifier>-<pid>.json.gz (or something similar, such as
* memory-reports-<identifier>-<pid>-1.json.gz; no existing file will be
* overwritten).
*
* If DMD is enabled, this method also dump gzipped DMD output to a file in
* the tmp directory called dmd-<identifier>-<pid>.txt.gz (or something
* similar; again, no existing file will be overwritten).
*
* @param aIdentifier this identifier will appear in the filename of our
* about:memory dump and those of our children (if aDumpChildProcesses is
* true).
*
* If the identifier is empty, the implementation may set it arbitrarily
* and use that new value for its own dump and the dumps of its child
* processes. For example, the implementation may set |aIdentifier| to the
* number of seconds since the epoch.
*
* @param aMinimizeMemoryUsage indicates whether we should run a series of
* gc/cc's in an attempt to reduce our memory usage before collecting our
* memory report.
*
* @param aDumpChildProcesses indicates whether we should call
* dumpMemoryInfoToTempDir in our child processes. If
* so, the child processes will also dump their children, and so on.
*/
void dumpMemoryInfoToTempDir(
in AString aIdentifier,
in bool aMinimizeMemoryUsage,
in bool aDumpChildProcesses);
/**
* Dump GC and CC logs to files in the OS's temp directory (or in
* $MOZ_CC_LOG_DIRECTORY, if that environment variable is specified).
*
* @param aIdentifier If aIdentifier is non-empty, this string will appear in
* the filenames of the logs we create (both for this process and, if
* aDumpChildProcesses is true, for our child processes).
*
* If aIdentifier is empty, the implementation may set it to an
* arbitrary value; for example, it may set aIdentifier to the number
* of seconds since the epoch.
*
* @param aDumpAllTraces indicates whether we should run an all-traces CC
* log. An all-traces log visits all objects currently eligible for cycle
* collection, while a non-all-traces log avoids visiting some objects
* which we know are reachable.
*
* All-traces logs are much bigger than the alternative, but they may be
* helpful when trying to understand why a particular object is alive. For
* example, a non-traces-log will skip references held by an active
* document; if your object is being held alive by such a document, you
* probably want to see those references.
*
* @param aDumpChildProcesses indicates whether we should call
* DumpGCAndCCLogsToFile in our child processes. If so, the child processes
* will dump their children, and so on.
*/
void dumpGCAndCCLogsToFile(in AString aIdentifier,
in bool aDumpAllTraces,
in bool aDumpChildProcesses);
};