pmc-rs 0.2.0 - Docs.rs

#![warn(missing_docs)]

//! `pmc-rs` provides a safe abstraction for interacting with Performance
//! Monitor Counters on [`FreeBSD`].
//!
//! PMCs are part of the CPU hardware and are typically used to profile CPU
//! micro-architecture events such as L1/L2/etc cache hit ratio, instructions
//! processed per CPU tick, TLB lookups, branch mispredictions, etc for a
//! particular application or algorithm. Using PMCs an algorithm can be tuned
//! for performance by minimising CPU stalls, optimising CPU cache usage, etc.
//!
//! The events are defined by the CPU manufacturer (here is the [Intel 64 and
//! IA-32 Architectures Developer's Manual: vol.
//! 3B](https://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-vol-3b-part-2-manual.html)
//! where the events can be found in section `18.2.1.2 "Pre-defined
//! Architectural Performance Events"`, `Table 18-1 "UMask and Event Select
//! Encodings for Pre-Defined Architectural Performance Events"`).
//!
//! `pmc-rs` makes use of [`libpmc`] and the [`hwpmc`] kernel module on
//! [`FreeBSD`].
//!
//! [`FreeBSD`]: https://www.freebsd.org/
//! [`hwpmc`]: https://www.freebsd.org/cgi/man.cgi?query=hwpmc
//! [`libpmc`]: https://www.freebsd.org/cgi/man.cgi?query=pmc

#[macro_use]
extern crate lazy_static;
extern crate libc;

mod signal;

mod error;
pub use error::*;

mod counter;
pub use counter::*;

#[cfg(not(target_os = "freebsd"))]
mod stubs;

#[cfg(not(target_os = "freebsd"))]
const _CPU_ANY: i32 = -1;
#[cfg(target_os = "freebsd")]
const _CPU_ANY: i32 = pmc_sys::PMC_CPU_ANY;

/// `Counter` instances allocated with `CPU_ANY` will measure events across all
/// CPUs.
///
/// `CPU_ANY` is a convenience value for readability and should be preferred
/// over using `0` directly.
pub const CPU_ANY: i32 = _CPU_ANY;

// TODO: add sampler type that records to a log file