Platform/Memory Reporting: Difference between revisions

Platform/Memory Reporting (view source)

Revision as of 04:01, 5 September 2013

875 bytes removed , 5 September 2013

→‎Normal and Multi-reporters

Nnethercote

Confirmed users

1,345

edits

@@ Line 3: / Line 3: @@
 Mozilla code 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.
-== Normal and Multi-reporters ==
+== Memory Reporters ==
-There are two basic ways to implement a memory reporter:  as a normal reporter, or a multi-reporter.
+A memory reporter makes one or more memory measurements (a.k.a. reports).  A reporter that only makes a single measurement is called a uni-reporter;  one that makes multiple measurements is called a multi-reporter.
-Normal reporters make a single memory measurement.  Each measurement involves several values, including:
+Each reporter implements a <tt>collectReports</tt> function which takes a <tt>nsIMemoryReporterCallback</tt> argument;  for each measurement the reporter must pass in several values, including:
-* a path (which identifies the reporter);
+* a path (which identifies the report);
 * an amount (the most important thing);
 * a unit (most commonly bytes, but sometimes a unitless count or percentage);
 * a description of what is measured.
-See the [https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIMemoryReporter nsIMemoryReporter documentation] and [http://mxr.mozilla.org/mozilla-central/source/xpcom/base/nsIMemoryReporter.idl nsIMemoryReporter.idl] for full details.  The <tt>NS_MEMORY_REPORTER_IMPLEMENT_HELPER</tt> macro makes simple memory reporters easy to write.
+See the [https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIMemoryReporter nsIMemoryReporter documentation] and [http://mxr.mozilla.org/mozilla-central/source/xpcom/base/nsIMemoryReporter.idl nsIMemoryReporter.idl] for full details.
-Multi-reporters make multiple memory measurements.  A multi-reporter implements a <tt>collectReports</tt> function which takes a <tt>nsIMemoryMultiReporterCallback</tt> argument;  for each measurement the multi-reporter must call the callback, passing in as arguments the same values that are provided for a normal reporter (path, amount, unit, etc).  See the [https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIMemoryMultiReporter nsIMemoryMultiReporter documentation] and [http://mxr.mozilla.org/mozilla-central/source/xpcom/base/nsIMemoryReporter.idl nsIMemoryReporter.idl] for full details.
+The <tt>MemoryUniReporter</tt> class makes memory uni-reporters easy to write.
-Normal reporters are best used if you have a small, fixed number of measurements to make.  Multi-reporters are best used if you have a large and/or non-fixed number of measurements to make (especially if you have one or more measurements per window/tab/compartment/whatever).  One disadvantage of multi-reporters is that you can't extract a single measurement from a multi-reporter easily, which means you can't use them from telemetry.
 == Making Measurements ==