JS::PerfMeasurementis 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.
JS::PerfMeasurement class, found in
jsperf.h, lets you take detailed performance measurements of your code. It is a stopwatch profiler -- that is, it counts events that occur while code of interest is running; it does not do call traces or sampling. The current implementation can measure eleven different types of low-level hardware and software events:
|Bitmask passed to constructor||Counter variable||What it measures|
| || ||Raw CPU clock cycles|
| || ||Total instructions executed|
| || ||Total number of memory accesses|
| || ||Memory accesses that missed the cache|
| || ||Branch instructions executed|
| || ||Branch instructions that were not predicted correctly|
| || ||Total memory bus cycles|
| || ||Total page-fault exceptions fielded by the OS|
| || ||Page faults that required disk access|
| || ||Context switches involving the profiled thread|
| || ||Migrations of the profiled thread from one CPU core to another|
These events map directly to "generic events" in the Linux 2.6.31+
<linux/perf_event.h> interface, and so unfortunately are a little vague in their specification; for instance, we can't tell you exactly which level of cache you get misses for if you measure
CACHE_MISSES. We also can't guarantee that all platforms will support all event types, once we have more than one back end for this interface.
Here is the complete C++-level API:
- This is an enumeration defining all of the bit mask values in the above table. You bitwise-OR the ones you want together and pass them to the constructor.
- In a constructor call, this special value means "measure everything that can possibly be measured."
- This constant equals the total number of events defined by the API - not necessarily the total number of events that a particular OS allows you to measure. (At time of writing, Linux allows all the above events to be measured, and we don't have back ends for any other operating system.
- static bool PerfMeasurement::canMeasureSomething()
- This class method returns true if and only if some -- not necessarily all -- events can be measured by the current build of SpiderMonkey, running on the current OS. At present, it returns true on Linux when the
<linux/perf_event.h>API is available (kernel 2.6.31 or later), and false everywhere else.
- PerfMeasurement::PerfMeasurement(EventMask toMeasure)
- The constructor creates a new profiling object, which measures some subset of the requested events.
- Take care not to leak profiling objects, as they may be holding down expensive OS-level state.
- EventMask eventsMeasured
- Instances of PerfMeasurement expose this constant. It will not have any more bits set than were set in the mask passed to the constructor, but if the OS cannot or will not measure all of the requested events, then only those events that will actually be measured have their bits set. All the counter variables for events that are not being measured will have the fixed value
- void start()
- Call this on a PerfMeasurement instance to start timing.
- void stop()
- And call this to stop timing again. The counter variables do not update in real time; they only change when
stopis called. Counter values are accumulated across many start/stop cycles, and you can modify their values if you want;
stopsimply adds counts read back from the OS to whatever is already in each counter.
- void reset()
- Resets all enabled counters to zero.
- uint64 cpu_cycles, uint64 instructions, etc.
- Each potentially-measurable event corresponds to a regular old instance variable, which you can read and even modify. All presently-measurable events are measured with counters, not timers; that is, there is no defined relation between the numbers you get from this interface, and wall-clock time.
- PerfMeasurement* JS::ExtractPerfMeasurement(jsval wrapper)
- JSObject* JS::RegisterPerfMeasurement(JSContext* cx, JSObject* global)