Platform/Memory Reporting

Gecko has infrastructure that lets different parts of the code report on their memory usage. This is most obviously used in about:memory and telemetry. This document describes things that you should know when writing a memory reporter.

Two Kinds of Memory Reporter

Memory reporters measure Firefox's memory usage. They are mainly used to generate the about:memory page.

There are two kinds of memory reporters.

- "Traversal-based" reporters traverse one or more data structures and

 measure the size of all the allocated blocks in the data structure.

- "Counter-based" reporters maintain a counter that is incremented on each

 relevant allocation and decremented on each relevant deallocation.

Traversal-based reporters are preferable.

- They are less error-prone (we've had multiple bugs in the past with

 counter-based reporters).  

- The cost of reporting isn't incurred unless the memory reporter is

 queried.

- They provide more information to DMD, which is a tool that helps keep

 about:memory's "heap-unclassified" number low (see bug 676724 for
 details).

But sometimes counter-based reporters are unavoidable.

Memory reporters should use the mozilla::MemoryReporterMallocSizeOf* functions declared below wherever possible for measuring heap-allocated blocks, for the following reasons.

- They ensure that slop bytes are counted on platforms that support

 malloc_usable_size or a similar function, while providing a |computedSize|
 fallback for other platforms.

- They provide some sanity checking on |computedSize| computations.

- They greatly simplify Firefox's integration with DMD.

traverse-based vs counter-based reporters

single vs. multi-reporters - multi can't be used for telemetry, otherwise fine

SizeOf function conventions

importance of using mallocSizeOf - slop - DMD can catch mistakes