Struct perf_event::Counter
source · pub struct Counter { /* private fields */ }
Expand description
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
sourceimpl Counter
impl Counter
sourcepub fn id(&self) -> u64
pub fn id(&self) -> u64
Return this counter’s kernel-assigned unique id.
This can be useful when iterating over Counts
.
sourcepub fn enable(&mut self) -> Result<()>
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 Counter
s as a single atomic operation.
sourcepub fn disable(&mut self) -> Result<()>
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 Counter
s as a single atomic operation.
sourcepub fn reset(&mut self) -> Result<()>
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 Counter
s as a single atomic operation.
sourcepub fn read(&mut self) -> Result<u64>
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 Counter
s’ values at once.
sourcepub fn read_count_and_time(&mut self) -> Result<CountAndTime>
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 Counter
s’ values at once.