rustc/vendor/perf-event

perf-event: a Rust interface to Linux performance monitoring

This is a nascent project. Tests are lacking. The design may change.

This uses the Linux perf_event_open API to access performance monitoring hardware and software. Use Builder to create a perf event counter, then use enable and disable to start and stop counting. Call read to get your count.

For example, this counts the number of cycles used by the call to println!. Try adjusting the length of the vector to see the cycle count change.

use perf_event::Builder;

fn main() -> std::io::Result<()> {
    let mut counter = Builder::new().build()?;

    let vec = (0..=51).collect::<Vec<_>>();

    counter.enable()?;
    println!("{:?}", vec);
    counter.disable()?;

    println!("{} instructions retired", counter.read()?);

    Ok(())
}

Since we don't specify what sort of event we want to count, Builder defaults to PERF_COUNT_HW_INSTRUCTIONS events, whose documentation says:

Retired instructions. Be careful, these can be affected by various issues, most notably hardware interrupt counts.

The examples directory includes programs that count other sorts of events.

See also

The perfcnt crate provides more extensive coverage of the Linux perf_event_open API than this crate. However, perfcnt does not build on stable Rust.