mozilla
/
gecko-dev
зеркало из https://github.com/mozilla/gecko-dev.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность
gecko-dev/xpcom/base/nsIMemoryReporter.idl

514 строки
20 KiB
Plaintext
Исходник Ответственный История

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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"
interface nsISimpleEnumerator;
interface nsIRunnable;
interface nsICancelableRunnable;
/*
* Memory reporters measure Firefox's memory usage. They are mainly used to
* generate the about:memory page. You should read
* https://wiki.mozilla.org/Memory_Reporting before writing a memory
* reporter.
*/
/*
* An nsIMemoryReporter reports a single memory measurement as an object.
* Use this when it makes sense to gather this measurement without gathering
* related measurements at the same time.
*
* Note that the |amount| field may be implemented as a function, and so
* accessing it can trigger significant computation; the other fields can
* be accessed without triggering this computation. (Compare and contrast
* this with nsIMemoryMultiReporter.)
*
* aboutMemory.js is the most important consumer of memory reports. It
* places the following constraints on reports.
*
* - There must be an "explicit" tree. It represents non-overlapping
* regions of memory that have been explicitly allocated with an
* OS-level allocation (e.g. mmap/VirtualAlloc/vm_allocate) or a
* heap-level allocation (e.g. malloc/calloc/operator new). Reporters
* in this tree must have kind HEAP or NONHEAP, units BYTES, and a
* description that is a sentence (i.e. starts with a capital letter and
* ends with a period, or similar).
*
* - The "size", "rss", "pss" and "swap" trees are optional. They
* represent regions of virtual memory that the process has mapped.
* Reporters in this category must have kind NONHEAP, units BYTES, and a
* non-empty description.
*
* - The "compartments" and "ghost-windows" trees are optional. They are
* used by about:compartments. Reporters in these trees must have kind
* OTHER, units COUNT, an amount of 1, and a description that's an empty
* string.
*
* - All other reports are unconstrained except that they must have a
* description that is a sentence.
*/
[scriptable, uuid(b2c39f65-1799-4b92-a806-ab3cf6af3cfa)]
interface nsIMemoryReporter : nsISupports
{
/*
* The name of the process containing this reporter. Each reporter initially
* has "" in this field, indicating that it applies to the current process.
* (This is true even for reporters in a child process.) When a reporter
* from a child process is copied into the main process, the copy has its
* 'process' field set appropriately.
*/
readonly attribute ACString process;
/*
* The path that this memory usage should be reported under. Paths are
* '/'-delimited, eg. "a/b/c".
*
* Each reporter can be viewed as representing a leaf node in a tree.
* Internal nodes of the tree don't have reporters. So, for example, the
* reporters "explicit/a/b", "explicit/a/c", "explicit/d/e", and
* "explicit/d/f" define this tree:
*
* explicit
* |--a
* | |--b [*]
* | \--c [*]
* \--d
* |--e [*]
* \--f [*]
*
* Nodes marked with a [*] have a reporter. Notice that the internal
* nodes are implicitly defined by the paths.
*
* Nodes within a tree should not overlap measurements, otherwise the
* parent node measurements will be double-counted. So in the example
* above, |b| should not count any allocations counted by |c|, and vice
* versa.
*
* All nodes within each tree must have the same units.
*
* If you want to include a '/' not as a path separator, e.g. because the
* path contains a URL, you need to convert each '/' in the URL to a '\'.
* Consumers of the path will undo this change. Any other '\' character
* in a path will also be changed. This is clumsy but hasn't caused any
* problems so far.
*
* The paths of all reporters form a set of trees. Trees can be
* "degenerate", i.e. contain a single entry with no '/'.
*/
readonly attribute AUTF8String path;
/*
* There are three kinds of memory reporters.
*
* - HEAP: reporters measuring memory allocated by the heap allocator,
* e.g. by calling malloc, calloc, realloc, memalign, operator new, or
* operator new[]. Reporters in this category must have units
* UNITS_BYTES.
*
* - NONHEAP: reporters measuring memory which the program explicitly
* allocated, but does not live on the heap. Such memory is commonly
* allocated by calling one of the OS's memory-mapping functions (e.g.
* mmap, VirtualAlloc, or vm_allocate). Reporters in this category
* must have units UNITS_BYTES.
*
* - OTHER: reporters which don't fit into either of these categories.
* They can have any units.
*
* The kind only matters for reporters in the "explicit" tree;
* aboutMemory.js uses it to calculate "heap-unclassified".
*/
const int32_t KIND_NONHEAP = 0;
const int32_t KIND_HEAP = 1;
const int32_t KIND_OTHER = 2;
/*
* The reporter kind. See KIND_* above.
*/
readonly attribute int32_t kind;
/*
* The amount reported by a memory reporter must have one of the following
* units, but you may of course add new units as necessary:
*
* - BYTES: The amount contains a number of bytes.
*
* - COUNT: The amount is an instantaneous count of things currently in
* existence. For instance, the number of tabs currently open would have
* units COUNT.
*
* - COUNT_CUMULATIVE: The amount contains the number of times some event
* has occurred since the application started up. For instance, the
* number of times the user has opened a new tab would have units
* COUNT_CUMULATIVE.
*
* The amount returned by a reporter with units COUNT_CUMULATIVE must
* never decrease over the lifetime of the application.
*
* - PERCENTAGE: The amount contains a fraction that should be expressed as
* a percentage. NOTE! The |amount| field should be given a value 100x
* the actual percentage; this number will be divided by 100 when shown.
* This allows a fractional percentage to be shown even though |amount| is
* an integer. E.g. if the actual percentage is 12.34%, |amount| should
* be 1234.
*
* Values greater than 100% are allowed.
*/
const int32_t UNITS_BYTES = 0;
const int32_t UNITS_COUNT = 1;
const int32_t UNITS_COUNT_CUMULATIVE = 2;
const int32_t UNITS_PERCENTAGE = 3;
/*
* The units on the reporter's amount. See UNITS_* above.
*/
readonly attribute int32_t units;
/*
* The numeric value reported by this memory reporter. Accesses can fail if
* something goes wrong when getting the amount.
*/
readonly attribute int64_t amount;
/*
* A human-readable description of this memory usage report.
*/
readonly attribute AUTF8String description;
};
[scriptable, function, uuid(5b15f3fa-ba15-443c-8337-7770f5f0ce5d)]
interface nsIMemoryMultiReporterCallback : nsISupports
{
void callback(in ACString process, in AUTF8String path, in int32_t kind,
in int32_t units, in int64_t amount,
in AUTF8String description, in nsISupports closure);
};
/*
* An nsIMemoryMultiReporter reports multiple memory measurements via a
* callback function which is called once for each measurement. Use this
* when you want to gather multiple measurements in a single operation (eg.
* a single traversal of a large data structure).
*
* The arguments to the callback deliberately match the fields in
* nsIMemoryReporter, but note that seeing any of these arguments requires
* calling collectReports which will trigger all relevant computation.
* (Compare and contrast this with nsIMemoryReporter, which allows all
* fields except |amount| to be accessed without triggering computation.)
*/
[scriptable, uuid(61d498d5-b460-4398-a8ea-7f75208534b4)]
interface nsIMemoryMultiReporter : nsISupports
{
/*
* The name of the multi-reporter. Useful when only one multi-reporter
* needs to be run. Must be unique; if multi-reporters share names it's
* likely the wrong one will be called in certain circumstances.
*/
readonly attribute ACString name;
/*
* Run the multi-reporter.
*/
void collectReports(in nsIMemoryMultiReporterCallback callback,
in nsISupports closure);
/*
* Return the sum of all this multi-reporter's measurements that have a
* path that starts with "explicit" and are KIND_NONHEAP.
*
* This is a hack that's required to implement
* nsIMemoryReporterManager::explicit efficiently, which is important --
* multi-reporters can special-case this operation so it's much faster
* than getting all the reports, filtering out the unneeded ones, and
* summing the remainder.
*/
readonly attribute int64_t explicitNonHeap;
};
[scriptable, builtinclass, uuid(0baaa958-3112-4952-b557-2a0c57eabb8f)]
interface nsIMemoryReporterManager : nsISupports
{
/*
* Return an enumerator of nsIMemoryReporters that are currently registered.
*/
nsISimpleEnumerator enumerateReporters ();
/*
* Return an enumerator of nsIMemoryMultiReporters that are currently
* registered.
*/
nsISimpleEnumerator enumerateMultiReporters ();
/*
* Register the given nsIMemoryReporter. After a reporter is registered,
* it will be available via enumerateReporters(). The Manager service
* will hold a strong reference to the given reporter.
*/
void registerReporter (in nsIMemoryReporter reporter);
/*
* Register the given nsIMemoryMultiReporter. After a multi-reporter is
* registered, it will be available via enumerateMultiReporters(). The
* Manager service will hold a strong reference to the given
* multi-reporter.
*/
void registerMultiReporter (in nsIMemoryMultiReporter reporter);
/*
* Unregister the given memory reporter.
*/
void unregisterReporter (in nsIMemoryReporter reporter);
/*
* Unregister the given memory multi-reporter.
*/
void unregisterMultiReporter (in nsIMemoryMultiReporter reporter);
/*
* Initialize.
*/
void init ();
/*
* Get the resident size (aka. RSS, physical memory used). This reporter
* is special-cased because it's interesting, is available on all
* platforms, and returns a meaningful result on all common platforms.
* Accesses can fail.
*/
readonly attribute int64_t resident;
/*
* Get the total size of explicit memory allocations, both at the OS-level
* (eg. via mmap, VirtualAlloc) and at the heap level (eg. via malloc,
* calloc, operator new). (Nb: it covers all heap allocations, but will
* miss any OS-level ones not covered by memory reporters.) This reporter
* is special-cased because it's interesting, and is moderately difficult
* to compute in JS. Accesses can fail.
*/
readonly attribute int64_t explicit;
/*
* This attribute indicates if moz_malloc_usable_size() works.
*/
[infallible] readonly attribute boolean hasMozMallocUsableSize;
/*
* Run a series of GC/CC's in an attempt to minimize the application's memory
* usage. When we're finished, we invoke the given runnable if it's not
* null. Returns a reference to the runnable used for carrying out the task.
*/
nsICancelableRunnable minimizeMemoryUsage(in nsIRunnable callback);
};
%{C++
#include "nsStringGlue.h"
// The NS_*MEMORY_REPORTER_IMPLEMENT* macros are the deprecated short-cut way
// of defining memory reporters. You should instead subclass the
// MemoryReporterBase class below.
// Note that this defaults 'process' to "", which is usually what's desired.
#define NS_MEMORY_REPORTER_IMPLEMENT_HELPER(_classname, _path, _kind, _units, _amountFunction, _desc, _ts) \
class MemoryReporter_##_classname MOZ_FINAL : public nsIMemoryReporter { \
public: \
NS_DECL_ISUPPORTS \
NS_IMETHOD GetProcess(nsACString &process) { process.Truncate(); return NS_OK; } \
NS_IMETHOD GetPath(nsACString &memoryPath) { memoryPath.AssignLiteral(_path); return NS_OK; } \
NS_IMETHOD GetKind(int *kind) { *kind = _kind; return NS_OK; } \
NS_IMETHOD GetUnits(int *units) { *units = _units; return NS_OK; } \
NS_IMETHOD GetAmount(int64_t *amount) { *amount = _amountFunction(); return NS_OK; } \
NS_IMETHOD GetDescription(nsACString &desc) { desc.AssignLiteral(_desc); return NS_OK; } \
}; \
NS_IMPL##_ts##ISUPPORTS1(MemoryReporter_##_classname, nsIMemoryReporter)
// The only difference between this and NS_MEMORY_REPORTER_IMPLEMENT_HELPER
// is that the function used to implement GetAmount is fallible.
#define NS_FALLIBLE_MEMORY_REPORTER_IMPLEMENT_HELPER(_classname, _path, _kind, _units, _amountFunction, _desc, _ts) \
class MemoryReporter_##_classname MOZ_FINAL : public nsIMemoryReporter { \
public: \
NS_DECL_ISUPPORTS \
NS_IMETHOD GetProcess(nsACString &process) { process.Truncate(); return NS_OK; } \
NS_IMETHOD GetPath(nsACString &memoryPath) { memoryPath.AssignLiteral(_path); return NS_OK; } \
NS_IMETHOD GetKind(int32_t *kind) { *kind = _kind; return NS_OK; } \
NS_IMETHOD GetUnits(int32_t *units) { *units = _units; return NS_OK; } \
NS_IMETHOD GetAmount(int64_t *amount) { return _amountFunction(amount); } \
NS_IMETHOD GetDescription(nsACString &desc) { desc.AssignLiteral(_desc); return NS_OK; }\
}; \
NS_IMPL##_ts##ISUPPORTS1(MemoryReporter_##_classname, nsIMemoryReporter)
#define NS_MEMORY_REPORTER_IMPLEMENT(_c, _p, _k, _u, _a, _d) \
NS_MEMORY_REPORTER_IMPLEMENT_HELPER(_c, _p, _k, _u, _a, _d, _)
#define NS_THREADSAFE_MEMORY_REPORTER_IMPLEMENT(_c, _p, _k, _u, _a, _d) \
NS_MEMORY_REPORTER_IMPLEMENT_HELPER(_c, _p, _k, _u, _a, _d, _THREADSAFE_)
#define NS_FALLIBLE_MEMORY_REPORTER_IMPLEMENT(_c, _p, _k, _u, _a, _d) \
NS_FALLIBLE_MEMORY_REPORTER_IMPLEMENT_HELPER(_c, _p, _k, _u, _a, _d, _)
#define NS_FALLIBLE_THREADSAFE_MEMORY_REPORTER_IMPLEMENT(_c, _p, _k, _u, _a, _d) \
NS_FALLIBLE_MEMORY_REPORTER_IMPLEMENT_HELPER(_c, _p, _k, _u, _a, _d, _THREADSAFE_)
#define NS_MEMORY_REPORTER_NAME(_classname) MemoryReporter_##_classname
// Note that the memory reporters are held in an nsCOMArray, which means
// that individual reporters should be referenced with |nsIMemoryReporter *|
// instead of nsCOMPtr<nsIMemoryReporter>.
nsresult NS_RegisterMemoryReporter(nsIMemoryReporter *reporter);
nsresult NS_RegisterMemoryMultiReporter(nsIMemoryMultiReporter *reporter);
nsresult NS_UnregisterMemoryReporter(nsIMemoryReporter *reporter);
nsresult NS_UnregisterMemoryMultiReporter(nsIMemoryMultiReporter *reporter);
#if defined(MOZ_DMD)
namespace mozilla {
namespace dmd {
// This runs all the memory reporters but does nothing with the results; i.e.
// it does the minimal amount of work possible for DMD to do its thing.
void RunReporters();
}
}
#endif // defined(MOZ_DMD)
#if defined(MOZ_DMD)
#if !defined(MOZ_MEMORY)
#error "MOZ_DMD requires MOZ_MEMORY"
#endif
#include "DMD.h"
#define MOZ_REPORT(ptr) mozilla::dmd::Report(ptr)
#define MOZ_REPORT_ON_ALLOC(ptr) mozilla::dmd::ReportOnAlloc(ptr)
#else
#define MOZ_REPORT(ptr)
#define MOZ_REPORT_ON_ALLOC(ptr)
#endif // defined(MOZ_DMD)
// Functions generated via this macro should be used by all traversal-based
// memory reporters. Such functions return |moz_malloc_size_of(ptr)|; this
// will always be zero on some obscure platforms.
//
// You might be wondering why we have a macro that creates multiple functions
// that differ only in their name, instead of a single
// MemoryReporterMallocSizeOf function. It's mostly to help with DMD
// integration, though it sometimes also helps with debugging and temporary ad
// hoc profiling. The function name chosen doesn't matter greatly, but it's
// best to make it similar to the path used by the relevant memory
// reporter(s).
#define NS_MEMORY_REPORTER_MALLOC_SIZEOF_FUN(fn) \
static size_t fn(const void *ptr) \
{ \
MOZ_REPORT(ptr); \
return moz_malloc_size_of(ptr); \
}
// Functions generated by the next two macros should be used by wrapping
// allocators that report heap blocks as soon as they are allocated and
// unreport them as soon as they are freed. Such allocators are used in cases
// where we have third-party code that we cannot modify. The two functions
// must always be used in tandem.
#define NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_ALLOC_FUN(fn) \
static size_t fn(const void *ptr) \
{ \
MOZ_REPORT_ON_ALLOC(ptr); \
return moz_malloc_size_of(ptr); \
}
#define NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_FREE_FUN(fn) \
static size_t fn(const void *ptr) \
{ \
return moz_malloc_size_of(ptr); \
}
namespace mozilla {
// The following base class reduces the amount of boilerplate code required for
// memory reporters. You just need to provide the following.
// - The constant values: path, kind, units, and description. They are passed
// to the MemoryReporterBase constructor.
// - A (private) Amount() or (public) GetAmount() method. It can use the
// MallocSizeOf method if necessary. Use Amount() if the reporter is
// infallible, and GetAmount() otherwise. (If you fail to provide one or the
// other, you'll get assertion failures when the memory reporter runs.)
//
// The class name of subclasses should match the path, minus the "explicit"
// (if present), and with "Reporter" at the end. For example:
// - "explicit/dom/xyzzy" --> DOMXyzzyReporter
// - "js-compartments/system" --> JSCompartmentsSystemReporter
//
class MemoryReporterBase : public nsIMemoryReporter
{
public:
MemoryReporterBase(const char* aPath, int32_t aKind, int32_t aUnits,
const char* aDescription)
: mPath(aPath)
, mKind(aKind)
, mUnits(aUnits)
, mDescription(aDescription)
{}
virtual ~MemoryReporterBase() {}
NS_DECL_ISUPPORTS
NS_IMETHOD GetProcess(nsACString& aProcess)
{
aProcess.Truncate();
return NS_OK;
}
NS_IMETHOD GetPath(nsACString& aPath)
{
aPath.Assign(mPath);
return NS_OK;
}
NS_IMETHOD GetKind(int32_t* aKind)
{
*aKind = mKind;
return NS_OK;
}
NS_IMETHOD GetUnits(int32_t* aUnits)
{
*aUnits = mUnits;
return NS_OK;
}
NS_IMETHOD GetAmount(int64_t* aAmount)
{
*aAmount = Amount();
return NS_OK;
}
NS_IMETHOD GetDescription(nsACString& aDescription)
{
aDescription.Assign(mDescription);
return NS_OK;
}
protected:
virtual int64_t Amount()
{
// We only reach here if neither GetAmount() nor Amount() was overridden.
MOZ_ASSERT(false);
return 0;
}
NS_MEMORY_REPORTER_MALLOC_SIZEOF_FUN(MallocSizeOf)
const nsCString mPath;
const int32_t mKind;
const int32_t mUnits;
const nsCString mDescription;
};
} // namespace mozilla
%}
Ссылка в новой задаче Показать git blame Копировать постоянную ссылку