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.

Method overview

Member fields

Recorded data 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).

Note: These values are all zeroed (or set to -1, for events not being measured) when you initialize the PerfMeasurement object, then they are not zeroed again unless you explicitly call the reset() method. This lets you accumulate measurements over multiple passes through code that you want to analyze.

Variable

Type

Description

cpu_cycles

uint64

The number of CPU cycles elapsed.

instructions

uint64

The number of instructions executed.

cache_references

uint64

The number of memory accesses that occurred.

cache_misses

uint64

The number of times memory accesses missed the cache.

branch_instructions

uint64

The number of branch instructions executed.

branch_misses

uint64

The number of times branch prediction guessed wrong.

bus_cycles

uint64

The number of memory bus cycles that elapsed.

page_faults

uint64

The number of page exceptions the OS handled.

major_page_faults

uint64

The number of times page faults required disk access.

context_switches

uint64

The number of context switches that occurred involving the thread being profiled.

cpu_migrations

uint64

The number of times the profiled thread migrated from one CPU core to another.

Event types measured constant

The eventsMeasured constant provides a mask indicating which event types were recorded.

Variable

Type

Description

eventsMeasured

EventMask

A bit mask of the event types recorded; this can differ from the events requested if the platform doesn't support all of the event types you specified when creating the PerfMeasurement object.

Constants

Event mask constants

These constants are used to construct the mask indicating which events you want to monitor.

Constant

Value

Description

CPU_CYCLES

0x00000001

Measure CPU cycles elapsed.

INSTRUCTIONS

0x00000002

Measure the number of instructions executed.

CACHE_REFERENCES

0x00000004

Measure the number of cache references.

CACHE_MISSES

0x00000008

Measure the number of cache misses.

BRANCH_INSTRUCTIONS

0x00000010

Measure the number of branch instructions executed.

BRANCH_MISSES

0x00000020

Measure the number of times branch prediction guesses wrong.

BUS_CYCLES

0x00000040

Measure the number of bus cycles elapsed.

PAGE_FAULTS

0x00000080

Measure the number of page faults that occurred.

MAJOR_PAGE_FAULTS

0x00000100

Measure the number of major page faults that occurred.

CONTEXT_SWITCHES

0x00000200

Measure the number of context switches that occurred.

CPU_MIGRATIONS

0x00000400

Measure the number of context switches that occurred.

ALL

0x000007FF

Measure all available events.

Number of available event types

The NUM_MEASURABLE_EVENTS constant tells you how many types of events can be measured.

Constant

Value

Description

NUM_MEASURABLE_EVENTS

11

The number of types of events that can be measured.

Constructor

Creates a new PerfMeasurement object, configured to record the specified event types.

PerfMeasurement(
EventMask toMeasure
);

Parameters

toMeasure

A mask of all of the event types you want to record; see Event mask constants for a list of values. OR together all the event types you want to record, and pass that value here. Pass PerfMeasurement.ALL to record all event types.

Return value

A new PerfMeasurement object configured to record the specified event types.

Methods

canMeasureSomething()

Indicates whether or not the platform on which your code is running supports this code module.

static bool canMeasureSomething();

Parameters

None.

Return value

If even one of the event types can be recorded, this will return true. Otherwise, it returns false.

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.