Struct GroupData

pub struct GroupData { /* private fields */ }

A collection of counts from a group of counters.

This is the type returned by Counter::read_group and Group::read. You can index it with a reference to a specific Counter:

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

let mut group = Group::new()?;
let cycles = group.add(&Builder::new(Hardware::CPU_CYCLES))?;
let insns = group.add(&Builder::new(Hardware::INSTRUCTIONS))?;
let counts = group.read()?;
println!(
    "cycles / instructions: {} / {} ({:.2} cpi)",
    counts[&cycles],
    counts[&insns],
    (counts[&cycles] as f64 / counts[&insns] as f64)
);

Or you can iterate over the results it contains:

for entry in &counts {
    println!("Counter id {} has value {}", entry.id(), entry.value());
}

The id values produced by this iteration are internal identifiers assigned by the kernel. You can use the Counter::id method to find a specific counter’s id.

For some kinds of events, the kernel may use timesharing to give all counters access to scarce hardware registers. You can see how long a group was actually running versus the entire time it was enabled using the time_enabled and time_running methods:

let scale =
    counts.time_enabled().unwrap().as_secs_f64() / counts.time_running().unwrap().as_secs_f64();
for entry in &counts {
    let value = entry.value() as f64 * scale;

    print!("Counter id {} has value {}", entry.id(), value as u64);
    if scale > 1.0 {
        print!(" (estimated)");
    }
    println!();
}

Implementations

impl GroupData

pub fn len(&self) -> usize

Return the number of counters this Counts holds results for.

pub fn is_empty(&self) -> bool

Whether this GroupData is empty.

pub fn time_enabled(&self) -> Option<Duration>

The duration for which the group was enabled.

This will only be present if TOTAL_TIME_ENABLED was passed to read_format.

pub fn time_running(&self) -> Option<Duration>

The duration for which the group was scheduled on the CPU.

This will only be present if TOTAL_TIME_RUNNING was passed to read_format.

pub fn get(&self, member: &Counter) -> Option<GroupEntry>

Get the entry for member in self, or None if member is not present.

member can be either a Counter or a Group.

If you know the counter is in the group then you can access the count via indexing.

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

let mut group = Group::new()?;
let instrs = Builder::new(Hardware::INSTRUCTIONS).build_with_group(&mut group)?;
let cycles = Builder::new(Hardware::CPU_CYCLES).build_with_group(&mut group)?;
group.enable()?;
// ...
let counts = group.read()?;
let instrs = counts[&instrs];
let cycles = counts[&cycles];

pub fn iter(&self) -> GroupIter<'_>

Return an iterator over all entries in self.

For compatibility reasons, if the Group this was

Example

let data = group.read()?;
for entry in &data {
    println!("Counter with id {} has value {}", entry.id(), entry.value());
}

Trait Implementations

impl Debug for GroupData

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

Formats the value using the given formatter.

impl Index<&Counter> for GroupData

type Output = u64

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'a> IntoIterator for &'a GroupData

type IntoIter = GroupIter<'a>

Which kind of iterator are we turning this into?

type Item = <GroupIter<'a> as Iterator>::Item

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.