/* -*- 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 nsICancelableRunnable; interface nsIDOMWindow; interface nsIRunnable; interface nsISimpleEnumerator; /* * Memory reporters measure Firefox's memory usage. They are primarily used to * generate the about:memory page. You should read * https://wiki.mozilla.org/Memory_Reporting before writing a memory * reporter. */ [scriptable, function, uuid(3a61be3b-b93b-461a-a4f8-388214f558b1)] interface nsIMemoryReporterCallback : nsISupports { /* * The arguments to the callback are as follows. * * * |process| 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. * * * |path| 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 '/'. * * * |kind| 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". * * * |units| The units on the reporter's amount. One of the following. * * - 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. * * * |amount| The numeric value reported by this memory reporter. Accesses * can fail if something goes wrong when getting the amount. * * * |description| A human-readable description of this memory usage report. */ 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 data); }; /* * An nsIMemoryReporter reports one or more memory measurements via a * callback function which is called once for each measurement. * * An nsIMemoryReporter that reports a single measurement is sometimes called a * "uni-reporter". One that reports multiple measurements is sometimes called * a "multi-reporter". * * 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). * * - All other reports are unconstrained except that they must have a * description that is a sentence. */ [scriptable, uuid(53248304-124b-43cd-99dc-6e5797b91618)] interface nsIMemoryReporter : nsISupports { /* * The name of the reporter. Useful when only one reporter needs to be run. * Must be unique; if reporters share names it's likely the wrong one will * be called in certain circumstances. */ readonly attribute ACString name; /* * Run the reporter. */ void collectReports(in nsIMemoryReporterCallback callback, in nsISupports data); /* * Kinds. See the |kind| comment in nsIMemoryReporterCallback. */ const int32_t KIND_NONHEAP = 0; const int32_t KIND_HEAP = 1; const int32_t KIND_OTHER = 2; /* * Units. See the |units| comment in nsIMemoryReporterCallback. */ 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; }; [scriptable, function, uuid(548b3909-c04d-4ca6-8466-b8bee3837457)] interface nsIFinishReportingCallback : nsISupports { void callback(in nsISupports data); }; [scriptable, builtinclass, uuid(2596fa26-495a-4827-a5f5-e34e7f4dd7b5)] interface nsIMemoryReporterManager : nsISupports { /* * Initialize. */ void init(); /* * 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); /* * Unregister the given memory reporter. */ void unregisterReporter(in nsIMemoryReporter reporter); /* * These functions should only be used for testing purposes. */ void blockRegistration(); void unblockRegistration(); void registerReporterEvenIfBlocked(in nsIMemoryReporter aReporter); /* * Return an enumerator of nsIMemoryReporters that are currently registered * in the current process. WARNING: this does not do anything with child * processes. Use getReports() if you want measurements from child * processes. */ nsISimpleEnumerator enumerateReporters(); /* * Get memory reports for the current process and all child processes. * |handleReport| is called for each report, and |finishReporting| is called * once all reports have been handled. * * |finishReporting| is called even if, for example, some child processes * fail to report back. However, calls to this method will silently and * immediately abort -- and |finishReporting| will not be called -- if a * previous getReports() call is still in flight, i.e. if it has not yet * finished invoking |finishReporting|. The silent abort is because the * in-flight request will finish soon, and the caller would very likely just * catch and ignore any error anyway. */ void getReports(in nsIMemoryReporterCallback handleReport, in nsISupports handleReportData, in nsIFinishReportingCallback finishReporting, in nsISupports finishReportingData); /* * The memory reporter manager, for the most part, treats reporters * registered with it as a black box. However, there are some * "distinguished" amounts (as could be reported by a memory reporter) that * the manager provides as attributes, because they are sufficiently * interesting that we want external code (e.g. telemetry) to be able to rely * on them. * * Note that these are not reporters and so enumerateReporters() does not * look at them. However, they can be embedded in a reporter. * * Access to these attributes can fail. In particular, some of them are not * available on all platforms. * * If you add a new distinguished amount, please update * toolkit/components/aboutmemory/tests/test_memoryReporters.xul. * * |explicit| (UNITS_BYTES) 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). It covers all heap allocations, * but will miss any OS-level ones not covered by memory reporters. * * |vsize| (UNITS_BYTES) The virtual size, i.e. the amount of address space * taken up. * * |vsizeMaxContiguous| (UNITS_BYTES) The size of the largest contiguous * block of virtual memory. * * |resident| (UNITS_BYTES) The resident size (a.k.a. RSS or physical memory * used). * * |residentFast| (UNITS_BYTES) This is like |resident|, but on Mac OS * |resident| can purge pages, which is slow. It also affects the result of * |residentFast|, and so |resident| and |residentFast| should not be used * together. * * |heapAllocated| (UNITS_BYTES) Memory mapped by the heap allocator. * * |heapOverheadRatio| (UNITS_PERCENTAGE) In the heap allocator, this is the * ratio of committed, unused bytes to allocated bytes. Like all * UNITS_PERCENTAGE measurements, its amount is multiplied by 100x so it can * be represented by an int64_t. * * |JSMainRuntimeGCHeap| (UNITS_BYTES) Size of the main JS runtime's GC * heap. * * |JSMainRuntimeTemporaryPeak| (UNITS_BYTES) Peak size of the transient * storage in the main JSRuntime. * * |JSMainRuntimeCompartments{System,User}| (UNITS_COUNT) The number of * {system,user} compartments in the main JS runtime. * * |imagesContentUsedUncompressed| (UNITS_BYTES) Memory used for decoded * images in content. * * |storageSQLite| (UNITS_BYTES) Memory used by SQLite. * * |lowMemoryEvents{Virtual,Physical}| (UNITS_COUNT_CUMULATIVE) The number * of low-{virtual,physical}-memory events that have occurred since the * process started. * * |ghostWindows| (UNITS_COUNT) The number of ghost windows. * * |pageFaultsHard| (UNITS_COUNT_CUMULATIVE) The number of hard (a.k.a. * major) page faults that have occurred since the process started. */ readonly attribute int64_t explicit; readonly attribute int64_t vsize; readonly attribute int64_t vsizeMaxContiguous; readonly attribute int64_t resident; readonly attribute int64_t residentFast; readonly attribute int64_t heapAllocated; readonly attribute int64_t heapOverheadRatio; readonly attribute int64_t JSMainRuntimeGCHeap; readonly attribute int64_t JSMainRuntimeTemporaryPeak; readonly attribute int64_t JSMainRuntimeCompartmentsSystem; readonly attribute int64_t JSMainRuntimeCompartmentsUser; readonly attribute int64_t imagesContentUsedUncompressed; readonly attribute int64_t storageSQLite; readonly attribute int64_t lowMemoryEventsVirtual; readonly attribute int64_t lowMemoryEventsPhysical; readonly attribute int64_t ghostWindows; readonly attribute int64_t pageFaultsHard; /* * 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); /* * Measure the memory that is known to be owned by this tab, split up into * several broad categories. Note that this will be an underestimate of the * true number, due to imperfect memory reporter coverage (corresponding to * about:memory's "heap-unclassified"), and due to some memory shared between * tabs not being counted. * * The time taken for the measurement (split into JS and non-JS parts) is * also returned. */ void sizeOfTab(in nsIDOMWindow window, out int64_t jsObjectsSize, out int64_t jsStringsSize, out int64_t jsOtherSize, out int64_t domSize, out int64_t styleSize, out int64_t otherSize, out int64_t totalSize, out double jsMilliseconds, out double nonJSMilliseconds); }; %{C++ #include "js/TypeDecls.h" #include "nsStringGlue.h" #include "nsTArray.h" class nsPIDOMWindow; // nsIHandleReportCallback is a better name, but keep nsIMemoryReporterCallback // around for backwards compatibility. typedef nsIMemoryReporterCallback nsIHandleReportCallback; // Note that the memory reporters are held in an nsCOMArray, which means // that individual reporters should be referenced with |nsIMemoryReporter *| // instead of nsCOMPtr. XPCOM_API(nsresult) NS_RegisterMemoryReporter(nsIMemoryReporter* aReporter); XPCOM_API(nsresult) NS_UnregisterMemoryReporter(nsIMemoryReporter* aReporter); namespace mozilla { // The memory reporter manager provides access to several distinguished // amounts via attributes. Some of these amounts are provided by Gecko // components that cannot be accessed directly from XPCOM code. So we provide // the following functions for those components to be registered with the // manager. typedef int64_t (*InfallibleAmountFn)(); typedef nsresult (*FallibleAmountFn)(int64_t* aAmount); #define DECL_REGISTER_DISTINGUISHED_AMOUNT(kind, name) \ nsresult Register##name##DistinguishedAmount(kind##AmountFn aAmountFn); #define DECL_UNREGISTER_DISTINGUISHED_AMOUNT(name) \ nsresult Unregister##name##DistinguishedAmount(); DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, JSMainRuntimeGCHeap) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, JSMainRuntimeTemporaryPeak) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, JSMainRuntimeCompartmentsSystem) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, JSMainRuntimeCompartmentsUser) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, ImagesContentUsedUncompressed) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, StorageSQLite) DECL_UNREGISTER_DISTINGUISHED_AMOUNT(StorageSQLite) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, LowMemoryEventsVirtual) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, LowMemoryEventsPhysical) DECL_REGISTER_DISTINGUISHED_AMOUNT(Infallible, GhostWindows) #undef DECL_REGISTER_DISTINGUISHED_AMOUNT #undef DECL_UNREGISTER_DISTINGUISHED_AMOUNT // Likewise for per-tab measurement. typedef nsresult (*JSSizeOfTabFn)(JSObject* aObj, size_t* aJsObjectsSize, size_t* aJsStringSize, size_t* aJsPrivateSize, size_t* aJsOtherSize); typedef nsresult (*NonJSSizeOfTabFn)(nsPIDOMWindow* aWindow, size_t* aDomSize, size_t* aStyleSize, size_t* aOtherSize); nsresult RegisterJSSizeOfTab(JSSizeOfTabFn aSizeOfTabFn); nsresult RegisterNonJSSizeOfTab(NonJSSizeOfTabFn aSizeOfTabFn); } #if defined(MOZ_DMD) namespace mozilla { namespace dmd { // This runs all the memory reporters in the current process but does nothing // with the results; i.e. it does the minimal amount of work possible for DMD // to do its thing. It does nothing with child processes. void RunReporters(); } } #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* aPtr) \ { \ MOZ_REPORT(aPtr); \ return moz_malloc_size_of(aPtr); \ } // 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* aPtr) \ { \ MOZ_REPORT_ON_ALLOC(aPtr); \ return moz_malloc_size_of(aPtr); \ } #define NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_FREE_FUN(fn) \ static size_t fn(const void* aPtr) \ { \ return moz_malloc_size_of(aPtr); \ } namespace mozilla { // The following base class reduces the amount of boilerplate code required for // memory uni-reporters. You just need to provide the following. // - The constant values: nameAndPath (which serves as both the reporters name, // and the path in its single report), kind, units, and description. They // are arguments to the MemoryUniReporter constructor. // - A private Amount() or public GetAmount() method. It can use the // MallocSizeOf method if necessary. (There is also // MallocSizeOfOn{Alloc,Free}, which can be useful.) 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 nameAndPath, minus the // "explicit" (if present), and with "Reporter" at the end. For example: // - nameAndPath == "explicit/dom/xyzzy" --> DOMXyzzyReporter // - nameAndPath == "js-compartments/system" --> JSCompartmentsSystemReporter // class MemoryUniReporter : public nsIMemoryReporter { public: MemoryUniReporter(const char* aNameAndPath, int32_t aKind, int32_t aUnits, const char* aDescription) : mNameAndPath(aNameAndPath) , mKind(aKind) , mUnits(aUnits) , mDescription(aDescription) {} virtual ~MemoryUniReporter() {} NS_DECL_THREADSAFE_ISUPPORTS NS_IMETHOD GetName(nsACString& aName) { aName.Assign(mNameAndPath); return NS_OK; } NS_IMETHOD CollectReports(nsIMemoryReporterCallback* aCallback, nsISupports* aData) { int64_t amount; nsresult rv = GetAmount(&amount); NS_ENSURE_SUCCESS(rv, rv); return aCallback->Callback(EmptyCString(), mNameAndPath, mKind, mUnits, amount, mDescription, aData); } protected: NS_IMETHOD GetAmount(int64_t* aAmount) { *aAmount = Amount(); return NS_OK; } 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) NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_ALLOC_FUN(MallocSizeOfOnAlloc) NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_FREE_FUN(MallocSizeOfOnFree) const nsCString mNameAndPath; const int32_t mKind; const int32_t mUnits; const nsCString mDescription; }; // The following base class reduces the amount of boilerplate code required for // memory multi-reporters. You just need to provide the following. // - The constant value: name. It is an argument to the MemoryMultiReporter // constructor. The name of each multi-reporter should be unique. // - A public CollectReports() method. It can use the MallocSizeOf method if // necessary. (There is also MallocSizeOfOn{Alloc,Free}, which can be // useful.) // // The class name of subclasses should match the name, with "Reporter" at // the end. For example: // - name == "foo" --> FooMultiReporter // class MemoryMultiReporter : public nsIMemoryReporter { public: MemoryMultiReporter(const char* aName) : mName(aName) {} virtual ~MemoryMultiReporter() {} NS_DECL_THREADSAFE_ISUPPORTS NS_IMETHOD GetName(nsACString& aName) { aName.Assign(mName); return NS_OK; } NS_IMETHOD CollectReports(nsIMemoryReporterCallback* aCb, nsISupports* aClosure) = 0; protected: NS_MEMORY_REPORTER_MALLOC_SIZEOF_FUN(MallocSizeOf) NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_ALLOC_FUN(MallocSizeOfOnAlloc) NS_MEMORY_REPORTER_MALLOC_SIZEOF_ON_FREE_FUN(MallocSizeOfOnFree) const nsCString mName; }; } // namespace mozilla %}