/* -*- 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 (original author) * Nicholas Nethercote * * 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". 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. * * There are several 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 leaf node in a tree * rooted at "explicit". 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. * * 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. * * Reporters in this category 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). * * - Paths starting with "smaps/" represent regions of virtual memory that the * process has mapped. The rest of the path describes the type of * measurement; for instance, the reporter "smaps/rss/[stack]" might report * how much of the process's stack is currently in physical memory. * * Reporters in this category must have kind NONHEAP, units BYTES, and * a non-empty description. * * - Reporters with kind SUMMARY may have any path which doesn't start with * "explicit/" or "smaps/". * * - All other paths represent cross-cutting values and may overlap with any * other reporter. Reporters in this category must have paths that do not * contain '/' separators, kind OTHER, and a description that is a * sentence. */ 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 "smaps/". * * - OTHER: reporters which don't fit into either of these categories. Such * reporters must have a path that does not start with "explicit/" or * "smaps/" and may have any units. * * - SUMMARY: reporters which report data that's available in a more * detailed form via other reporters. These reporters are sometimes * useful for efficiency purposes -- for example, a KIND_SUMMARY reporter * might list all the JS compartments without the overhead of the full JS * memory reporter, which walks the JS heap. * * Unlike other reporters, SUMMARY reporters may have empty descriptions. * * SUMMARY reporters must not have a path starting with "explicit/" or * "smaps/". */ const PRInt32 KIND_NONHEAP = 0; const PRInt32 KIND_HEAP = 1; const PRInt32 KIND_OTHER = 2; const PRInt32 KIND_SUMMARY = 3; /* * 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. * * Values greater than 100% are allowed. */ 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. Accesses can fail if * something goes 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(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 PRInt64 explicitNonHeap; }; [scriptable, uuid(4527b1d8-a81f-4af3-9623-80e4120392c7)] 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 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. Accesses can fail. */ readonly attribute PRInt64 explicit; /* * This attribute indicates if moz_malloc_usable_size() works. */ readonly attribute boolean hasMozMallocUsableSize; }; %{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 MOZ_FINAL : 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) /* * 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.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) { return _amountFunction(amount); } \ 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_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 nsresult NS_RegisterMemoryReporter(nsIMemoryReporter *reporter); nsresult NS_RegisterMemoryMultiReporter(nsIMemoryMultiReporter *reporter); nsresult NS_UnregisterMemoryReporter(nsIMemoryReporter *reporter); nsresult NS_UnregisterMemoryMultiReporter(nsIMemoryMultiReporter *reporter); // Because DMD is not a tool that comes with the standard Valgrind // distribution, we have to #include our own local copy of dmd.h. Ugly but // unavoidable. #ifdef MOZ_DMD #if MOZ_MEMORY #error "--disable-jemalloc should have been forced when --enable-dmd was specified" #endif #include "dmd.h" #endif namespace mozilla { /* * 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 * distinguished only by |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 |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, name) \ static size_t fn(const void *ptr) \ { \ size_t usable = moz_malloc_size_of(ptr); \ VALGRIND_DMD_REPORT(ptr, usable, name); \ return usable; \ } /* * Like NS_MEMORY_REPORTER_MALLOC_SIZEOF_FUN, but the created function sends an * "unreport" message to DMD. */ #define NS_MEMORY_REPORTER_MALLOC_SIZEOF_FUN_UN(fn) \ static size_t fn(const void *ptr) \ { \ size_t usable = moz_malloc_size_of(ptr); \ VALGRIND_DMD_UNREPORT(ptr); \ return usable; \ } #ifdef MOZ_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. Then * it dumps the DMD output to stderr (or somewhere else, if one of * DMD/Valgrind's logging options was used). */ void DMDCheckAndDump(); #else #define VALGRIND_DMD_REPORT(ptr, usable, name) #define VALGRIND_DMD_UNREPORT(ptr) #endif /* defined(MOZ_DMD) */ } %}