Struct perf_event::Group

pub struct Group { /* fields omitted */ }

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(&group).kind(Hardware::CPU_CYCLES).build()?;
let insns = Builder::new().group(&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 xreturn an error. Unfortunately, there is no way at present to specify a Groups task and cpu, so you can only use Group on the calling task.

Methods

impl Group

pub fn new() -> Result<Group>

Construct a new, empty Group.

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.

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.

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(&group).kind(...).build()?;
let counter2 = Builder::new().group(&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);

Trait Implementations

impl Debug for Group

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

Formats the value using the given formatter.