gecko/xpcom/base/nsIMemoryReporter.idl

382 lines
16 KiB
Plaintext

/* -*- Mode: C++; tab-width: 50; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is
* mozilla.org
* Portions created by the Initial Developer are Copyright (C) 2008
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Vladimir Vukicevic <vladimir@pobox.com> (original author)
* Nicholas Nethercote <nnethercote@mozilla.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsISimpleEnumerator;
/*
* 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.)
*/
[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". There are three categories of paths.
*
* - Paths starting with "explicit" represent regions of memory that have
* been explicitly allocated with an OS-level allocation (eg.
* mmap/VirtualAlloc/vm_allocate) or a heap-level allocation (eg.
* malloc/calloc/operator new).
*
* Each reporter can be viewed as representing a node in a tree rooted at
* "explicit". Not all nodes of the tree need have an associated reporter.
* So, for example, the reporters "explicit/a/b", "explicit/a/c",
* "explicit/d", "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 "explicit/a" is
* implicitly defined.
*
* A node's children divide their parent's memory into disjoint pieces.
* So in the example above, |a| may not count any allocations counted by
* |d|, and vice versa.
*
* - Paths starting with "map" represent regions of virtual memory that the
* process has mapped. The reporter immediately beneath "map" describes
* the type of measurement; for instance, the reporter "map/rss/[stack]"
* might report how much of the process's stack is currently in physical
* memory.
*
* Reporters in this category must have kind NONHEAP and units BYTES.
*
* - All other paths represent cross-cutting values and may overlap with any
* other reporter.
*/
readonly attribute AUTF8String path;
/*
* There are three categories of memory reporters:
*
* - HEAP: 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 and must have a path
* starting with "explicit".
* - NONHEAP: 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
* and must have a path starting with "explicit" or "map".
*
* - OTHER: reporters which don't fit into either of these categories. Such
* reporters must have a path that does not start with "explicit" or "map"
* and may have any units.
*/
const PRInt32 KIND_NONHEAP = 0;
const PRInt32 KIND_HEAP = 1;
const PRInt32 KIND_OTHER = 2;
/*
* KIND_MAPPED is a deprecated synonym for KIND_NONHEAP. We keep it around
* to as not to break extensions which might use this interface, but we will
* remove it eventually.
*/
const PRInt32 KIND_MAPPED = 0;
/*
* The reporter kind. See KIND_* above.
*/
readonly attribute PRInt32 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.
*/
const PRInt32 UNITS_BYTES = 0;
const PRInt32 UNITS_COUNT = 1;
const PRInt32 UNITS_COUNT_CUMULATIVE = 2;
const PRInt32 UNITS_PERCENTAGE = 3;
/*
* The units on the reporter's amount. See UNITS_* above.
*/
readonly attribute PRInt32 units;
/*
* The numeric value reported by this memory reporter. -1 means "unknown",
* ie. something went wrong when getting the amount.
*/
readonly attribute PRInt64 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 PRInt32 kind,
in PRInt32 units, in PRInt64 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(eae277ad-b67d-4389-95f4-03fa11c09d06)]
interface nsIMemoryMultiReporter : nsISupports
{
void collectReports(in nsIMemoryMultiReporterCallback callback,
in nsISupports closure);
};
[scriptable, uuid(84ba9c85-3372-4423-b7ab-74708b9269a6)]
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.
* -1 means unknown.
*/
readonly attribute PRInt64 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. -1 means unknown.
*/
readonly attribute PRInt64 explicit;
};
%{C++
/*
* 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 : public nsIMemoryReporter { \
public: \
NS_DECL_ISUPPORTS \
NS_IMETHOD GetProcess(nsACString &process) { process.Truncate(); return NS_OK; } \
NS_IMETHOD GetPath(nsACString &memoryPath) { memoryPath.Assign(_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(PRInt64 *amount) { *amount = _amountFunction(); return NS_OK; } \
NS_IMETHOD GetDescription(nsACString &desc) { desc.Assign(_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_MEMORY_REPORTER_NAME(_classname) MemoryReporter_##_classname
nsresult NS_RegisterMemoryReporter (nsIMemoryReporter *reporter);
nsresult NS_RegisterMemoryMultiReporter (nsIMemoryMultiReporter *reporter);
nsresult NS_UnregisterMemoryReporter (nsIMemoryReporter *reporter);
nsresult NS_UnregisterMemoryMultiReporter (nsIMemoryMultiReporter *reporter);
namespace mozilla {
/*
* This function should be used by all traversal-based memory reporters.
* - On platforms where moz_malloc_usable_size() returns 0 it just returns
* |computedSize| (this happens on platforms where malloc_usable_size() or
* equivalent isn't available).
* - Otherwise, it |returns moz_malloc_usable_size(p)|, but only after doing
* some sanity checking -- it will assert if the usable size is too
* dissimilar to |computedSize|. (However, this checking is skipped if
* |computedSize| is zero, which is useful if the computation is not worth
* the effort, e.g. because it's tricky and the |computedSize| would be
* small.)
*/
size_t MemoryReporterMallocSizeOf(const void *ptr, size_t computedSize);
/*
* These functions are like MemoryReporterMallocSizeOf(), and should be used by
* all counter-based memory reporters when incrementing/decrementing a counter.
*/
size_t MemoryReporterMallocSizeOfForCounterInc(const void *ptr,
size_t computedSize);
size_t MemoryReporterMallocSizeOfForCounterDec(const void *ptr,
size_t computedSize);
/*
* For the purposes of debugging, temporary profiling, and DMD integration, it
* is sometimes useful to temporarily create multiple variants of
* MemoryReporterMallocSizeOf(), with each one distinguished by a string
* |name|. This macro makes creating such variants easy. |name| isn't used,
* but it will be if extra debugging code is temporarily added.
*/
#define NS_MEMORY_REPORTER_MALLOC_SIZEOF_FUN(fn, name) \
size_t fn(const void *ptr, size_t computedSize) \
{ \
size_t usable = moz_malloc_usable_size((void*)ptr); \
if (!usable) { \
return computedSize; \
} \
NS_MEMORY_REPORTER_CHECK_SIZES(usable, computedSize); \
return usable; \
}
/*
* This is used by the MemoryReporterMallocSizeOf* functions for checking
* usable against computedSize.
*/
#define NS_MEMORY_REPORTER_CHECK_SIZES(usable, computedSize) \
do { \
/* The factor of two is because no reasonable heap allocator will */ \
/* return a block more than twice the requested size. The one */ \
/* exception is that a request less than N bytes may be rounded up */ \
/* by the allocator to N bytes (we use N = 16 in our checking */ \
/* because that's what the default allocator on Mac uses). Also, if */ \
/* computedSize is 0 we don't check it against usable. */ \
NS_ASSERTION(usable >= computedSize, \
"MemoryReporterMallocSizeOf: computedSize is too big"); \
NS_ASSERTION(usable < computedSize * 2 || usable <= 16 || \
computedSize == 0, \
"MemoryReporterMallocSizeOf: computedSize is too small"); \
} while(0)
}
%}