/* -*- 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(24d61ead-237b-4969-a6bd-73fd8fed1d99)] 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); }; [scriptable, builtinclass, uuid(70b0e608-8dbf-4dc7-b88f-f1c745c1b48c)] 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); /** * These functions should only be used for testing purposes. */ void blockRegistration(); void unblockRegistration(); void registerReporterEvenIfBlocked(in nsIMemoryReporter aReporter); void registerMultiReporterEvenIfBlocked(in nsIMemoryMultiReporter aReporter); /* * Initialize. */ void init (); /* * Get the resident size (aka. RSS, physical memory used). This reporter * is special-cased because it's interesting and is available on most * 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. XPCOM_API(nsresult) NS_RegisterMemoryReporter(nsIMemoryReporter *reporter); XPCOM_API(nsresult) NS_RegisterMemoryMultiReporter(nsIMemoryMultiReporter *reporter); XPCOM_API(nsresult) NS_UnregisterMemoryReporter(nsIMemoryReporter *reporter); XPCOM_API(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 %}