mozilla

Revision 97465 of PerfMeasurement.jsm

  • Revision slug: JavaScript_code_modules/PerfMeasurement.jsm
  • Revision title: PerfMeasurement.jsm
  • Revision id: 97465
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment more content, wip; 324 words added, 51 words removed

Revision Content

{{ gecko_minversion_header("2.0") }}

The PerfMeasurement.jsm JavaScript code module lets you take detailed performance measurements of your code.

{{ note("The PerfMeasurement.jsm JavaScript code module can only be used from chrome -- that is, from within the application itself or an add-on.") }}

Before you can use this module, you need to import it into your scope:

Components.utils.import("resource://gre/modules/PerfMeasurement.jsm")

You can then create a PerfMeasurement object. You give the constructor a bit-mask of events you're interested in.

Note: At present, PerfMeasurement.jsm is only functional on Linux, but it is planned to add support for Windows ({{ Bug("583322") }}) and OSX ({{ Bug("583323") }}) as well, and we welcome patches for other operating systems.

For instance, let's measure instructions executed, cache references, and cache misses:

let monitor = new PerfMeasurement(PerfMeasurement.CPU_CYCLES | PerfMeasurement.CACHE_REFERENCES | PerfMeasurement.CACHE_MISSES);

This just sets up to measure stuff, it doesn't start timing anything.  Now, we want to benchmark a function that is pretty fast (but not fast enough), so we run it several thousand times:

for (let i = 0; i < 10000; i++) {
  set_up_some_state();
  monitor.start();
  code_to_be_benchmarked();
  monitor.stop();
  clean_up_afterward();
}

Only the work done by code_to_be_benchmarked(), not set_up_some_state() or clean_up_afterward(), will be measured.  The monitor object automatically accumulates counts over start/stop cycles.  When you're done benchmarking, you can read out each of the counters you asked for as properties:

let report = "CPU cycles:   " + monitor.cpu_cycles + "\n" +
             "Cache refs:   " + monitor.cache_references + "\n" +
             "Cache misses: " + monitor.cache_misses + "\n";
monitor.reset();
alert(report);

The reset method clears all of the enabled counters, as you might expect.  When you're done with your measurements, just let the monitor object go out of scope.

For more details, including a complete list of events that can be measured, see the C++ documentation.

Method overview

void reset();
void start();
void stop();

Member variables

These variables provide access to the recorded data. Any measurable event that was not being recorded has a value of -1 (that is, 0xFFFFFFFFFFFFFFFF).

Variable Type Description
key DOMString Represents the key changed. The key attribute is null when the change is caused by the storage clear() method. Read only.
newValue DOMString The new value of the key. The newValue is null when the change has been invoked by storage clear() method or the key has been removed from the storage. Read only.
oldValue DOMString The original value of the key. The oldValue is null when the change has been invoked by storage clear() method or the key has been newly added and therefor doesn't have any previous value. Read only.
storageArea {{ Interface("nsIDOMStorage") }} Represents the Storage object that was affected. Read only.
url DOMString The URL of the document whose key changed. Read only.

Methods

reset()

Resets all the enabled counters to zero.

void reset();
Parameters

None.

start()

Starts measuring the performance indicators that were specified when the PerfMeasurement object was created.

void start();
Parameters

None.

stop()

Stops measuring performance data. For each enabled counter, the number of measured events of that type that occurred are added to the appropriate visible variable.

void stop();
Parameters

None.

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p><code>The PerfMeasurement.jsm</code> JavaScript code module lets you take detailed performance measurements of your code.</p>
<p>{{ note("The <code>PerfMeasurement.jsm</code> JavaScript code module can only be used from chrome -- that is, from within the application itself or an add-on.") }}</p>
<p>Before you can use this module, you need to import it into your scope:</p>
<pre class="brush: js"><span class="nowiki">Components.utils.import("resource://gre/modules/PerfMeasurement.jsm")</span></pre>
<p>You can then create a <code>PerfMeasurement</code> object. You give the constructor a bit-mask of events you're interested in.</p>
<div class="note"><strong>Note:</strong> At present, <code>PerfMeasurement.jsm</code> is only functional on Linux, but it is planned to add support for Windows ({{ Bug("583322") }}) and OSX ({{ Bug("583323") }}) as well, and we welcome patches for other operating systems.</div>
<p>For instance, let's measure instructions executed, cache references, and cache misses:</p>
<pre class="brush: js"><span class="nowiki">let monitor = new PerfMeasurement(PerfMeasurement.CPU_CYCLES | PerfMeasurement.CACHE_REFERENCES | PerfMeasurement.CACHE_MISSES);</span></pre>
<p>This just sets up to measure stuff, it doesn't start timing anything.  Now, we want to benchmark a function that is pretty fast (but not fast enough), so we run it several thousand times:</p>
<pre class="brush: js">for (let i = 0; i &lt; 10000; i++) {
  set_up_some_state();
  monitor.start();
  code_to_be_benchmarked();
  monitor.stop();
  clean_up_afterward();
}
</pre>
<p>Only the work done by <code>code_to_be_benchmarked()</code>, not <code>set_up_some_state()</code> or <code>clean_up_afterward()</code>, will be measured.  The <code>monitor</code> object automatically accumulates counts over start/stop cycles.  When you're done benchmarking, you can read out each of the counters you asked for as properties:</p>
<pre class="brush: js">let report = "CPU cycles:   " + monitor.cpu_cycles + "\n" +
             "Cache refs:   " + monitor.cache_references + "\n" +
             "Cache misses: " + monitor.cache_misses + "\n";
monitor.reset();
alert(report);
</pre>
<p>The <code>reset</code> method clears all of the enabled counters, as you might expect.  When you're done with your measurements, just let the <code>monitor</code> object go out of scope.</p>
<p>For more details, including a complete list of events that can be measured, see the <a href="/en/JS::PerfMeasurement" title="en/JS::PerfMeasurement">C++ documentation</a>.</p>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="/en/JavaScript_code_modules/PerfMeasurement.jsm#reset()" title="en/JavaScript code modules/PerfMeasurement.jsm#reset()">reset</a>();<br> </code></td> </tr> <tr> <td><code>void <a href="/en/JavaScript_code_modules/PerfMeasurement.jsm#start()" title="en/JavaScript code modules/PerfMeasurement.jsm#start()">start</a>();<br> </code></td> </tr> <tr> <td><code>void <a href="/en/JavaScript_code_modules/PerfMeasurement.jsm#stop()" title="en/JavaScript code modules/PerfMeasurement.jsm#stop()">stop</a>();<br> </code></td> </tr> </tbody>
</table>
<h2>Member variables</h2>
<p>These variables provide access to the recorded data. Any measurable event that was not being recorded has a value of -1 (that is, 0xFFFFFFFFFFFFFFFF).</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Variable</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>key</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>Represents the key changed. The <code>key</code> attribute is <code>null</code> when the change is caused by the storage <code>clear()</code> method. <strong>Read only.</strong></td> </tr> <tr> <td><code>newValue</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>The new value of the <code>key</code>. The <code>newValue</code> is <code>null</code> when the change has been invoked by storage <code>clear()</code> method or the <code>key</code> has been removed from the storage. <strong>Read only.</strong></td> </tr> <tr> <td><code>oldValue</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>The original value of the <code>key</code>. The <code>oldValue</code> is <code>null</code> when the change has been invoked by storage <code>clear()</code> method or the <code>key</code> has been newly added and therefor doesn't have any previous value. <strong>Read only.</strong></td> </tr> <tr> <td><code>storageArea</code></td> <td><code>{{ Interface("nsIDOMStorage") }}</code></td> <td>Represents the Storage object that was affected. <strong>Read only.</strong></td> </tr> <tr> <td><code>url</code></td> <td><code><a href="/en/DOMString" title="en/DOMString">DOMString</a></code></td> <td>The URL of the document whose <code>key</code> changed. <strong>Read only.</strong></td> </tr>  </tbody>
</table>
<h2>Methods</h2>
<h3>reset()</h3>
<p>Resets all the enabled counters to zero.</p>
<pre>void reset();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h3>start()</h3>
<p>Starts measuring the performance indicators that were specified when the <code>PerfMeasurement</code> object was created.</p>
<pre>void start();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h3>stop()</h3>
<p>Stops measuring performance data. For each enabled counter, the number of measured events of that type that occurred are added to the appropriate visible variable.</p>
<pre>void stop();
</pre>
<h6>Parameters</h6>
<p>None.</p>
Revert to this revision