perf_event/events/
mod.rs

1//! Events we can monitor or count.
2//!
3//! There are a few general categories of event:
4//!
5//! - [`Hardware`] events are counted by the processor itself. This includes
6//!   things like clock cycles, instructions retired, and cache and branch
7//!   prediction statistics.
8//!
9//! - [`Cache`] events, also counted by the processor, offer a more detailed
10//!   view of the processor's cache counters. You can select which level of the
11//!   cache hierarchy to observe, discriminate between data and instruction
12//!   caches, and so on.
13//!
14//! - [`Software`] events are counted by the kernel. This includes things like
15//!   context switches, page faults, and so on.
16//!
17//! - [`Breakpoint`] events correspond to hardware breakpoints. They can count
18//!   read/write accesses to an address as well as execution of an instruction
19//!   address.
20//!
21//! Linux supports many more kinds of events than this module covers, including
22//! events specific to particular make and model of processor, and events that
23//! are dynamically registered by drivers and kernel modules. If something you
24//! want is missing, think about the best API to expose it, and submit a pull
25//! request!
26
27use std::sync::Arc;
28
29use perf_event_open_sys::bindings::perf_event_attr;
30
31use crate::events::util::CachedPmuType;
32use crate::{Builder, Counter};
33
34used_in_docs!(Counter);
35used_in_docs!(Builder);
36
37pub mod x86;
38
39mod breakpoint;
40mod cache;
41mod dynamic;
42mod hardware;
43mod probe;
44mod raw;
45mod software;
46mod tracepoint;
47mod util;
48
49/// Non-io errors emitted when constructing events.
50pub mod error {
51    pub use crate::events::dynamic::{DynamicBuilderError, MissingParameterError};
52}
53
54pub use self::breakpoint::{Breakpoint, BreakpointAccess};
55#[allow(deprecated)]
56pub use self::cache::WhichCache;
57pub use self::cache::{Cache, CacheId, CacheOp, CacheResult};
58pub use self::dynamic::{Dynamic, DynamicBuilder};
59pub use self::hardware::Hardware;
60pub use self::probe::{KProbe, UProbe};
61pub use self::raw::Raw;
62pub use self::software::Software;
63pub use self::tracepoint::Tracepoint;
64
65/// An event that we can monitor or count.
66pub trait Event: Sized {
67    /// Update the [`perf_event_attr`] struct so that it will record the
68    /// requested event.
69    ///
70    /// The field that need to be set in order to configure the kernel to
71    /// collect various events can vary by quite a bit so this crate avoids
72    /// putting any restrictions here by just passing the whole
73    /// [`perf_event_attr`] struct.
74    fn update_attrs(self, attr: &mut perf_event_attr);
75
76    /// Update the [`perf_event_attr`] struct so that it will record the
77    /// requested event.
78    ///
79    /// This is exactly the same as `update_attrs` except it optionally allows
80    /// the Event implementor to return data that needs to live until the
81    /// actual [`Counter`] is constructed.
82    ///
83    /// [`Builder`] will always call this method instead of `update_attrs`.
84    fn update_attrs_with_data(self, attr: &mut perf_event_attr) -> Option<Arc<dyn EventData>> {
85        self.update_attrs(attr);
86        None
87    }
88}
89
90/// Trait for owned event data.
91///
92/// This is automatically implemented for any type which is both `Send` and
93/// `Sync`.
94pub trait EventData: Send + Sync {}
95
96impl<T: Send + Sync> EventData for T {}
perf_event/events/mod.rs

perf_event/events/
mod.rs
