Struct perf_event::Builder

pub struct Builder<'a> { /* fields omitted */ }

A builder for Counters.

There are dozens of parameters that influence a Counter's behavior. Builder lets you construct a Counter by specifying only those parameters for which you don't want the default value.

A freshly built Counter is disabled. To begin counting events, you must call enable on the Counter or the Group to which it belongs.

For example, if you want a Counter for instructions retired by the current process, those are Builder's defaults, so you need only write:

let mut insns = Builder::new().build()?;

The kind method lets you specify what sort of event you want to count. So if you'd rather count branch instructions:

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

The group method lets you gather individual counters into Group that can be enabled or disabled atomically:

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()?;

Other methods let you select:

• specific processes or cgroups to observe
• specific CPU cores to observe

Builder supports only a fraction of the many knobs and dials Linux offers, but hopefully it will acquire methods to support more of them as time goes on.

Methods

impl<'a> Builder<'a>

pub fn new() -> Builder<'a>

Return a new Builder, with all parameters set to their defaults.

pub fn observe_self(self) -> Builder<'a>

Observe the calling process. (This is the default.)

pub fn observe_pid(self, pid: pid_t) -> Builder<'a>

Observe the process with the given process id. This requires CAP_SYS_PTRACE capabilities.

pub fn observe_cgroup(self, cgroup: &'a File) -> Builder<'a>

Observe code running in the given cgroup (container). The cgroup argument should be a File referring to the cgroup's directory in the cgroupfs filesystem.

pub fn one_cpu(self, cpu: usize) -> Builder<'a>

Observe only code running on the given CPU core.

pub fn any_cpu(self) -> Builder<'a>

Observe code running on any CPU core. (This is the default.)

pub fn kind<K: Into<Event>>(self, kind: K) -> Builder<'a>

Count events of the given kind. This accepts an Event value, or any type that can be converted to one, so you can pass Hardware, Software and Cache values directly.

The default is to count retired instructions, or Hardware::INSTRUCTIONS events.

For example, to count level 1 data cache references and misses, pass the appropriate events::Cache values:

use perf_event::{Builder, Group};
use perf_event::events::{Cache, CacheOp, CacheResult, WhichCache};

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

pub fn group(self, group: &'a Group) -> Builder<'a>

Place the counter in the given Group. Groups allow a set of counters to be enabled, disabled, or read as a single atomic operation, so that the counts can be usefully compared.

pub fn build(self) -> Result<Counter>

Construct a Counter according to the specifications made on this Builder.

A freshly built Counter is disabled. To begin counting events, you must call enable on the Counter or the Group to which it belongs.

Unfortunately, problems in counter configuration are detected at this point, by the kernel, not earlier when the offending request is made on the Builder. The kernel's returned errors are not always helpful.

Trait Implementations

impl<'a> Default for Builder<'a>

fn default() -> Builder<'a>

Returns the "default value" for a type.