Struct Counter 

pub struct Counter { /* private fields */ }

A counter for one kind of kernel or hardware event.

A Counter represents a single performance monitoring counter. You select what sort of event you’d like to count when the Counter is created, then you can enable and disable the counter, call its read method to retrieve the current count, and reset it to zero.

A Counter’s value is always a u64.

For example, this counts the number of instructions retired (completed) during a call to println!.

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(())
}

It is often useful to count several different quantities over the same period of time. For example, if you want to measure the average number of clock cycles used per instruction, you must count both clock cycles and instructions retired, for the same range of execution. The [Group] type lets you enable, disable, read, and reset any number of counters simultaneously.

When a counter is dropped, its kernel resources are freed along with it.

Internally, a Counter is just a wrapper around an event file descriptor.

Implementations

impl Counter

pub fn id(&self) -> u64

Return this counter’s kernel-assigned unique id.

This can be useful when iterating over Counts.

pub fn enable(&mut self) -> Result<()>

Allow this Counter to begin counting its designated event.

This does not affect whatever value the Counter had previously; new events add to the current count. To clear a Counter, use the reset method.

Note that Group also has an enable method, which enables all its member Counters as a single atomic operation.

Examples found in repository

examples/println.rs (line 8)

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(())
}

examples/insns-for-pid.rs (line 20)

fn main() -> std::io::Result<()> {
    let pid: pid_t = std::env::args()
        .nth(1)
        .expect("Usage: insns-for-pid PID")
        .parse()
        .expect("Usage: insns-for-pid PID");

    let mut insns = Builder::new()
        .observe_pid(pid)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;

    // Count instructions in PID for five seconds.
    insns.enable()?;
    sleep(Duration::from_secs(5));
    insns.disable()?;

    println!("instructions in last five seconds: {}", insns.read()?);

    Ok(())
}

pub fn disable(&mut self) -> Result<()>

Make this Counter stop counting its designated event. Its count is unaffected.

Note that Group also has a disable method, which disables all its member Counters as a single atomic operation.

Examples found in repository

examples/println.rs (line 10)

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(())
}

examples/insns-for-pid.rs (line 22)

fn main() -> std::io::Result<()> {
    let pid: pid_t = std::env::args()
        .nth(1)
        .expect("Usage: insns-for-pid PID")
        .parse()
        .expect("Usage: insns-for-pid PID");

    let mut insns = Builder::new()
        .observe_pid(pid)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;

    // Count instructions in PID for five seconds.
    insns.enable()?;
    sleep(Duration::from_secs(5));
    insns.disable()?;

    println!("instructions in last five seconds: {}", insns.read()?);

    Ok(())
}

pub fn reset(&mut self) -> Result<()>

Reset the value of this Counter to zero.

Note that Group also has a reset method, which resets all its member Counters as a single atomic operation.

pub fn read(&mut self) -> Result<u64>

Return this Counter’s current value as a u64.

Consider using the read_count_and_time method instead of this one. Some counters are implemented in hardware, and the processor can support only a certain number running at a time. If more counters are requested than the hardware can support, the kernel timeshares them on the hardware. This method gives you no indication whether this has happened; read_count_and_time does.

Note that Group also has a read method, which reads all its member Counters’ values at once.

Examples found in repository

examples/println.rs (line 12)

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(())
}

examples/insns-for-pid.rs (line 24)

fn main() -> std::io::Result<()> {
    let pid: pid_t = std::env::args()
        .nth(1)
        .expect("Usage: insns-for-pid PID")
        .parse()
        .expect("Usage: insns-for-pid PID");

    let mut insns = Builder::new()
        .observe_pid(pid)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;

    // Count instructions in PID for five seconds.
    insns.enable()?;
    sleep(Duration::from_secs(5));
    insns.disable()?;

    println!("instructions in last five seconds: {}", insns.read()?);

    Ok(())
}

pub fn read_count_and_time(&mut self) -> Result<CountAndTime>

Return this Counter’s current value and timesharing data.

Some counters are implemented in hardware, and the processor can run only a fixed number of them at a time. If more counters are requested than the hardware can support, the kernel timeshares them on the hardware.

This method returns a CountAndTime struct, whose count field holds the counter’s value, and whose time_enabled and time_running fields indicate how long you had enabled the counter, and how long the counter was actually scheduled on the processor. This lets you detect whether the counter was timeshared, and adjust your use accordingly. Times are reported in nanoseconds.

let cat = counter.read_count_and_time()?;
if cat.time_running == 0 {
    println!("No data collected.");
} else if cat.time_running < cat.time_enabled {
    // Note: this way of scaling is accurate, but `u128` division
    // is usually implemented in software, which may be slow.
    println!("{} instructions (estimated)",
             (cat.count as u128 *
              cat.time_enabled as u128 / cat.time_running as u128) as u64);
} else {
    println!("{} instructions", cat.count);
}

Note that Group also has a read method, which reads all its member Counters’ values at once.

Trait Implementations

impl AsRawFd for Counter

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Counter

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Index<&Counter> for Counts

type Output = u64

The returned type after indexing.

fn index(&self, index: &Counter) -> &u64

Performs the indexing (container[index]) operation.

impl IntoRawFd for Counter

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.