perf_event_open/
lib.rs

1//! Full-featured high-level wrapper for the `perf_event_open` system call.
2//!
3//! ## Example
4//!
5//! Count how many instructions executed for the (inefficient) fibonacci caculation
6//! and samples the user stack for it.
7//!
8//! ```rust
9//! use perf_event_open::config::{Cpu, Opts, Proc, SampleOn, Size};
10//! use perf_event_open::count::Counter;
11//! use perf_event_open::event::hw::Hardware;
12//!
13//! // Count retired instructions on current process, all CPUs.
14//! let event = Hardware::Instr;
15//! let target = (Proc::CURRENT, Cpu::ALL);
16//!
17//! let mut opts = Opts::default();
18//! opts.sample_on = SampleOn::Freq(1000); // 1000 samples per second.
19//! opts.sample_format.user_stack = Some(Size(8)); // Dump 8-bytes user stack in sample.
20//!
21//! let counter = Counter::new(event, target, opts).unwrap();
22//! let sampler = counter.sampler(10).unwrap(); // Allocate 2^10 pages to store samples.
23//!
24//! counter.enable().unwrap(); // Start the counter.
25//! fn fib(n: usize) -> usize {
26//!     match n {
27//!         0 => 0,
28//!         1 => 1,
29//!         n => fib(n - 1) + fib(n - 2),
30//!     }
31//! }
32//! std::hint::black_box(fib(30));
33//! counter.disable().unwrap(); // Stop the counter.
34//!
35//! let instrs = counter.stat().unwrap().count;
36//! println!("{} instructions retired", instrs);
37//!
38//! for it in sampler.iter() {
39//!     println!("{:-?}", it);
40//! }
41//! ```
42//!
43//! ## Kernel compatibility
44//!
45//! Any Linux kernel since 4.0 is supported.
46//!
47//! Please use the Linux version features to ensure your binary is compatible with
48//! the target host kernel. These features are backwards compatible, e.g.
49//! `linux-6.11` works with Linux 6.12 but may not work with Linux 6.10.
50//!
51//! The `legacy` feature is compatible with the oldest LTS kernel that still in
52//! maintaince, or you can use the `latest` feature if you dont't care about the
53//! kernel compatibility.
54
55pub mod config;
56pub mod count;
57pub mod event;
58mod ffi;
59pub mod sample;
perf_event_open/lib.rs

perf_event_open/
lib.rs
