Struct Group 

pub struct Group { /* private fields */ }

A group of counters that can be managed as a unit.

A Group represents a group of Counters that can be enabled, disabled, reset, or read as a single atomic operation. This is necessary if you want to compare counter values, produce ratios, and so on, since those operations are only meaningful on counters that cover exactly the same period of execution.

A Counter is placed in a group when it is created, by calling the Builder’s group method. A Group’s read method returns values of all its member counters at once as a Counts value, which can be indexed by Counter to retrieve a specific value.

For example, the following program computes the average number of cycles used per instruction retired for a call to println!:

use perf_event::{Builder, Group};
use perf_event::events::Hardware;

let mut group = Group::new()?;
let cycles = Builder::new().group(&mut group).kind(Hardware::CPU_CYCLES).build()?;
let insns = Builder::new().group(&mut group).kind(Hardware::INSTRUCTIONS).build()?;

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

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

let counts = group.read()?;
println!("cycles / instructions: {} / {} ({:.2} cpi)",
         counts[&cycles],
         counts[&insns],
         (counts[&cycles] as f64 / counts[&insns] as f64));

The lifetimes of Counters and Groups are independent: placing a Counter in a Group does not take ownership of the Counter, nor must the Counters in a group outlive the Group. If a Counter is dropped, it is simply removed from its Group, and omitted from future results. If a Group is dropped, its individual counters continue to count.

Enabling or disabling a Group affects each Counter that belongs to it. Subsequent reads from the Counter will not reflect activity while the Group was disabled, unless the Counter is re-enabled individually.

A Group and its members must all observe the same tasks and cpus; mixing these makes building the Counter return an error. Unfortunately, there is no way at present to specify a Group’s task and cpu, so you can only use Group on the calling task. If this is a problem, please file an issue.

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

Limits on group size

Hardware counters are implemented using special-purpose registers on the processor, of which there are only a fixed number. (For example, an Intel high-end laptop processor from 2015 has four such registers per virtual processor.) Without using groups, if you request more hardware counters than the processor can actually support, a complete count isn’t possible, but the kernel will rotate the processor’s real registers amongst the measurements you’ve requested to at least produce a sample.

But since the point of a counter group is that its members all cover exactly the same period of time, this tactic can’t be applied to support large groups. If the kernel cannot schedule a group, its counters remain zero. I think you can detect this situation by comparing the group’s time_enabled and time_running values. It might also be useful to set the pinned bit, which puts the counter in an error state if it’s not able to be put on the CPU; see [#10].

According to the perf_list(1) man page, you may be able to free up a hardware counter by disabling the kernel’s NMI watchdog, which reserves one for detecting kernel hangs:

$ echo 0 > /proc/sys/kernel/nmi_watchdog

You can reenable the watchdog when you’re done like this:

$ echo 1 > /proc/sys/kernel/nmi_watchdog

Implementations

impl Group

pub fn new() -> Result<Group>

Construct a new, empty Group.

Examples found in repository

examples/println-cpi.rs (line 5)

fn main() -> std::io::Result<()> {
    use perf_event::events::Hardware;
    use perf_event::{Builder, Group};

    let mut group = Group::new()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;

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

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

    let counts = group.read()?;
    println!(
        "cycles / instructions: {} / {} ({:.2} cpi)",
        counts[&cycles],
        counts[&insns],
        (counts[&cycles] as f64 / counts[&insns] as f64)
    );

    Ok(())
}

examples/group.rs (line 15)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.

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

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

    let counts = group.read()?;
    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

examples/locality.rs (line 88)

fn measure(label: &str, task: impl FnOnce()) {
    use perf_event::events::{Cache, CacheOp, CacheResult, WhichCache};
    use perf_event::{Builder, Group};

    let mut group = Group::new().expect("creating group is ok");
    let read_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building read_counter is ok");
    let read_miss_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::MISS,
        })
        .build()
        .expect("building read_miss_counter is ok");
    let prefetch_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::PREFETCH,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building prefetch_counter is ok");

    group.enable().expect("enabling group is ok");
    task();
    group.disable().expect("disabling group is ok");

    let counts = group.read().expect("reading group is ok");
    let reads = counts[&read_counter];
    let read_misses = counts[&read_miss_counter];
    let read_hits = reads - read_misses;
    let prefetches = counts[&prefetch_counter];

    println!(
        "{label}: hits / reads: {read_hits:8} / {reads:8} {:6.2}%, \
         prefetched {prefetches:8}",
        (read_hits as f64 / reads as f64) * 100.0,
    );

    if counts.time_enabled() != counts.time_running() {
        println!(
            "time enabled: {}  time running: {}",
            counts.time_enabled(),
            counts.time_running(),
        );
    }
}

examples/big-group.rs (line 15)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.
    //
    // On my machine, this program won't collect any data unless I disable the
    // NMI watchdog, as described in the documentation for `Group`. My machine
    // has four counters, and this program tries to use all of them, but the NMI
    // watchdog uses one up.

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

    group.enable()?;
    vec.sort();
    println!("{:?}", &vec[0..10]);
    group.disable()?;

    let counts = group.read()?;

    println!(
        "enabled for {}ns, actually running for {}ns",
        counts.time_enabled(),
        counts.time_running()
    );

    if counts.time_running() == 0 {
        println!("Group was never running; no results available.");
        return Ok(());
    }

    if counts.time_running() < counts.time_enabled() {
        println!("Counts cover only a portion of the execution.");
    }

    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    println!(
        "{} instructions, {} cycles ({:.2} cpi)",
        counts[&insns],
        counts[&cycles],
        counts[&cycles] as f64 / counts[&insns] as f64
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

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

Allow all Counters in this Group to begin counting their designated events, as a single atomic operation.

This does not affect whatever values the Counters had previously; new events add to the current counts. To clear the Counters, use the reset method.

Examples found in repository

examples/println-cpi.rs (line 17)

fn main() -> std::io::Result<()> {
    use perf_event::events::Hardware;
    use perf_event::{Builder, Group};

    let mut group = Group::new()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;

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

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

    let counts = group.read()?;
    println!(
        "cycles / instructions: {} / {} ({:.2} cpi)",
        counts[&cycles],
        counts[&insns],
        (counts[&cycles] as f64 / counts[&insns] as f64)
    );

    Ok(())
}

examples/group.rs (line 33)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.

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

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

    let counts = group.read()?;
    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

examples/locality.rs (line 117)

fn measure(label: &str, task: impl FnOnce()) {
    use perf_event::events::{Cache, CacheOp, CacheResult, WhichCache};
    use perf_event::{Builder, Group};

    let mut group = Group::new().expect("creating group is ok");
    let read_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building read_counter is ok");
    let read_miss_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::MISS,
        })
        .build()
        .expect("building read_miss_counter is ok");
    let prefetch_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::PREFETCH,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building prefetch_counter is ok");

    group.enable().expect("enabling group is ok");
    task();
    group.disable().expect("disabling group is ok");

    let counts = group.read().expect("reading group is ok");
    let reads = counts[&read_counter];
    let read_misses = counts[&read_miss_counter];
    let read_hits = reads - read_misses;
    let prefetches = counts[&prefetch_counter];

    println!(
        "{label}: hits / reads: {read_hits:8} / {reads:8} {:6.2}%, \
         prefetched {prefetches:8}",
        (read_hits as f64 / reads as f64) * 100.0,
    );

    if counts.time_enabled() != counts.time_running() {
        println!(
            "time enabled: {}  time running: {}",
            counts.time_enabled(),
            counts.time_running(),
        );
    }
}

examples/big-group.rs (line 46)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.
    //
    // On my machine, this program won't collect any data unless I disable the
    // NMI watchdog, as described in the documentation for `Group`. My machine
    // has four counters, and this program tries to use all of them, but the NMI
    // watchdog uses one up.

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

    group.enable()?;
    vec.sort();
    println!("{:?}", &vec[0..10]);
    group.disable()?;

    let counts = group.read()?;

    println!(
        "enabled for {}ns, actually running for {}ns",
        counts.time_enabled(),
        counts.time_running()
    );

    if counts.time_running() == 0 {
        println!("Group was never running; no results available.");
        return Ok(());
    }

    if counts.time_running() < counts.time_enabled() {
        println!("Counts cover only a portion of the execution.");
    }

    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    println!(
        "{} instructions, {} cycles ({:.2} cpi)",
        counts[&insns],
        counts[&cycles],
        counts[&cycles] as f64 / counts[&insns] as f64
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

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

Make all Counters in this Group stop counting their designated events, as a single atomic operation. Their counts are unaffected.

Examples found in repository

examples/println-cpi.rs (line 19)

fn main() -> std::io::Result<()> {
    use perf_event::events::Hardware;
    use perf_event::{Builder, Group};

    let mut group = Group::new()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;

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

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

    let counts = group.read()?;
    println!(
        "cycles / instructions: {} / {} ({:.2} cpi)",
        counts[&cycles],
        counts[&insns],
        (counts[&cycles] as f64 / counts[&insns] as f64)
    );

    Ok(())
}

examples/group.rs (line 35)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.

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

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

    let counts = group.read()?;
    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

examples/locality.rs (line 119)

fn measure(label: &str, task: impl FnOnce()) {
    use perf_event::events::{Cache, CacheOp, CacheResult, WhichCache};
    use perf_event::{Builder, Group};

    let mut group = Group::new().expect("creating group is ok");
    let read_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building read_counter is ok");
    let read_miss_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::MISS,
        })
        .build()
        .expect("building read_miss_counter is ok");
    let prefetch_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::PREFETCH,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building prefetch_counter is ok");

    group.enable().expect("enabling group is ok");
    task();
    group.disable().expect("disabling group is ok");

    let counts = group.read().expect("reading group is ok");
    let reads = counts[&read_counter];
    let read_misses = counts[&read_miss_counter];
    let read_hits = reads - read_misses;
    let prefetches = counts[&prefetch_counter];

    println!(
        "{label}: hits / reads: {read_hits:8} / {reads:8} {:6.2}%, \
         prefetched {prefetches:8}",
        (read_hits as f64 / reads as f64) * 100.0,
    );

    if counts.time_enabled() != counts.time_running() {
        println!(
            "time enabled: {}  time running: {}",
            counts.time_enabled(),
            counts.time_running(),
        );
    }
}

examples/big-group.rs (line 49)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.
    //
    // On my machine, this program won't collect any data unless I disable the
    // NMI watchdog, as described in the documentation for `Group`. My machine
    // has four counters, and this program tries to use all of them, but the NMI
    // watchdog uses one up.

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

    group.enable()?;
    vec.sort();
    println!("{:?}", &vec[0..10]);
    group.disable()?;

    let counts = group.read()?;

    println!(
        "enabled for {}ns, actually running for {}ns",
        counts.time_enabled(),
        counts.time_running()
    );

    if counts.time_running() == 0 {
        println!("Group was never running; no results available.");
        return Ok(());
    }

    if counts.time_running() < counts.time_enabled() {
        println!("Counts cover only a portion of the execution.");
    }

    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    println!(
        "{} instructions, {} cycles ({:.2} cpi)",
        counts[&insns],
        counts[&cycles],
        counts[&cycles] as f64 / counts[&insns] as f64
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

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

Reset all Counters in this Group to zero, as a single atomic operation.

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

Return the values of all the Counters in this Group as a Counts value.

A Counts value is a map from specific Counters to their values. You can find a specific Counter’s value by indexing:

let mut group = Group::new()?;
let counter1 = Builder::new().group(&mut group).kind(...).build()?;
let counter2 = Builder::new().group(&mut group).kind(...).build()?;
...
let counts = group.read()?;
println!("Rhombus inclinations per taxi medallion: {} / {} ({:.0}%)",
         counts[&counter1],
         counts[&counter2],
         (counts[&counter1] as f64 / counts[&counter2] as f64) * 100.0);

Examples found in repository

examples/println-cpi.rs (line 21)

fn main() -> std::io::Result<()> {
    use perf_event::events::Hardware;
    use perf_event::{Builder, Group};

    let mut group = Group::new()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;

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

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

    let counts = group.read()?;
    println!(
        "cycles / instructions: {} / {} ({:.2} cpi)",
        counts[&cycles],
        counts[&insns],
        (counts[&cycles] as f64 / counts[&insns] as f64)
    );

    Ok(())
}

examples/group.rs (line 37)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.

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

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

    let counts = group.read()?;
    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

examples/locality.rs (line 121)

fn measure(label: &str, task: impl FnOnce()) {
    use perf_event::events::{Cache, CacheOp, CacheResult, WhichCache};
    use perf_event::{Builder, Group};

    let mut group = Group::new().expect("creating group is ok");
    let read_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building read_counter is ok");
    let read_miss_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::READ,
            result: CacheResult::MISS,
        })
        .build()
        .expect("building read_miss_counter is ok");
    let prefetch_counter = Builder::new()
        .group(&mut group)
        .kind(Cache {
            which: WhichCache::L1D,
            operation: CacheOp::PREFETCH,
            result: CacheResult::ACCESS,
        })
        .build()
        .expect("building prefetch_counter is ok");

    group.enable().expect("enabling group is ok");
    task();
    group.disable().expect("disabling group is ok");

    let counts = group.read().expect("reading group is ok");
    let reads = counts[&read_counter];
    let read_misses = counts[&read_miss_counter];
    let read_hits = reads - read_misses;
    let prefetches = counts[&prefetch_counter];

    println!(
        "{label}: hits / reads: {read_hits:8} / {reads:8} {:6.2}%, \
         prefetched {prefetches:8}",
        (read_hits as f64 / reads as f64) * 100.0,
    );

    if counts.time_enabled() != counts.time_running() {
        println!(
            "time enabled: {}  time running: {}",
            counts.time_enabled(),
            counts.time_running(),
        );
    }
}

examples/big-group.rs (line 51)

fn main() -> std::io::Result<()> {
    const ACCESS: Cache = Cache {
        which: WhichCache::L1D,
        operation: CacheOp::READ,
        result: CacheResult::ACCESS,
    };
    const MISS: Cache = Cache {
        result: CacheResult::MISS,
        ..ACCESS
    };

    let mut group = Group::new()?;
    let access_counter = Builder::new().group(&mut group).kind(ACCESS).build()?;
    let miss_counter = Builder::new().group(&mut group).kind(MISS).build()?;
    let branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_INSTRUCTIONS)
        .build()?;
    let missed_branches = Builder::new()
        .group(&mut group)
        .kind(Hardware::BRANCH_MISSES)
        .build()?;
    let insns = Builder::new()
        .group(&mut group)
        .kind(Hardware::INSTRUCTIONS)
        .build()?;
    let cycles = Builder::new()
        .group(&mut group)
        .kind(Hardware::CPU_CYCLES)
        .build()?;

    // Note that if you add more counters than you actually have hardware for,
    // the kernel will time-slice them, which means you may get no coverage for
    // short measurements. See the documentation.
    //
    // On my machine, this program won't collect any data unless I disable the
    // NMI watchdog, as described in the documentation for `Group`. My machine
    // has four counters, and this program tries to use all of them, but the NMI
    // watchdog uses one up.

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

    group.enable()?;
    vec.sort();
    println!("{:?}", &vec[0..10]);
    group.disable()?;

    let counts = group.read()?;

    println!(
        "enabled for {}ns, actually running for {}ns",
        counts.time_enabled(),
        counts.time_running()
    );

    if counts.time_running() == 0 {
        println!("Group was never running; no results available.");
        return Ok(());
    }

    if counts.time_running() < counts.time_enabled() {
        println!("Counts cover only a portion of the execution.");
    }

    println!(
        "L1D cache misses/references: {} / {} ({:.0}%)",
        counts[&miss_counter],
        counts[&access_counter],
        (counts[&miss_counter] as f64 / counts[&access_counter] as f64) * 100.0
    );

    println!(
        "branch prediction misses/total: {} / {} ({:.0}%)",
        counts[&missed_branches],
        counts[&branches],
        (counts[&missed_branches] as f64 / counts[&branches] as f64) * 100.0
    );

    println!(
        "{} instructions, {} cycles ({:.2} cpi)",
        counts[&insns],
        counts[&cycles],
        counts[&cycles] as f64 / counts[&insns] as f64
    );

    // You can iterate over a `Counts` value:
    for (id, value) in &counts {
        println!("Counter id {} has value {}", id, value);
    }

    Ok(())
}

Trait Implementations

impl AsRawFd for Group

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Group

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

Formats the value using the given formatter.

impl IntoRawFd for Group

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.