pmc-rs 0.2.2

A safe abstraction for interacting with Performance Monitor Counters on FreeBSD.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

#![allow(missing_docs)]

use std::{fmt, io};

#[derive(Debug)]
pub struct Error {
    kind: ErrorKind,
    cause: Option<Box<dyn std::error::Error>>,
}

#[derive(Debug, PartialEq)]
pub enum ErrorKind {
    /// An unknown error
    Unknown,

    /// The signal handler received an unrecognised signal.
    UnexpectedSignal,

    /// Failed to initialise [`libpmc`].
    ///
    /// [`libpmc`]: https://www.freebsd.org/cgi/man.cgi?query=pmc
    Init,

    /// The system CPU does not support performance monitor counters.
    Unsupported,

    /// The kernel PMC interface differs from what this crate is using.
    ///
    /// This usually means FreeBSD/hwpmc has been updated - recompiling the
    /// application might help.
    VersionMismatch,

    /// The provided event specification is not recognised.
    InvalidEventSpec,

    /// `AllocInit` is returned for generic `Counter` initialisation errors, and
    /// unfortunately can be caused by other errors (such as
    /// [`InvalidEventSpec`]) without providing any more information.
    ///
    /// [`InvalidEventSpec`]: #variant.InvalidEventSpec
    AllocInit,

    /// The [`hwpmc`] kernel module has been unloaded.
    ///
    /// In testing, this signal was not sent from the [`hwpmc`] implementation,
    /// so this error should not be relied upon.
    ///
    /// [`hwpmc`]: https://www.freebsd.org/cgi/man.cgi?query=hwpmc
    Unloaded,

    /// The [`Counter`] is already attached to the requested process.
    ///
    /// [`Counter`]: struct.Counter.html
    AlreadyAttached,

    /// The requested [scope] is invalid for the requested event.
    ///
    /// [scope]: enum.Scope.html
    BadScope,

    /// The requested event requires a configured log file to write results to.
    LogFileRequired,

    /// The requested target PID is already being monitored by another process.
    BusyTarget,

    /// The requested target PID does not exist.
    BadTarget,

    /// The caller does not have the appropriate permissions.
    Forbidden,
}

impl std::error::Error for Error {
    fn description(&self) -> &str {
        match self.kind {
            ErrorKind::Init => "missing hwpmc in kernel",
            ErrorKind::Unloaded => "hwpmc unloaded from kernel",
            ErrorKind::Unsupported => "unsupported CPU",
            ErrorKind::VersionMismatch => "unexpected hwpmc version",
            ErrorKind::AllocInit => "failed to allocate counter",
            ErrorKind::BusyTarget => "target is busy",
            ErrorKind::BadTarget => "target PID does not exist",
            ErrorKind::AlreadyAttached => "PMC already attached to target process",
            ErrorKind::Forbidden => "forbidden",
            _ => "unknown error",
        }
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}", self)
    }
}

#[doc(hidden)]
impl PartialEq for Error {
    fn eq(&self, other: &Error) -> bool {
        self.kind == other.kind
    }
}

impl Error {
    pub fn kind(&self) -> &ErrorKind {
        &self.kind
    }

    pub fn cause(&self) -> Option<&dyn std::error::Error> {
        self.cause.as_deref()
    }
}

pub(crate) fn new_os_error(kind: ErrorKind) -> Error {
    // Get the last OS error to reference as the cause
    Error {
        kind,
        cause: Some(Box::new(io::Error::last_os_error())),
    }
}

pub(crate) fn new_error(kind: ErrorKind) -> Error {
    Error { kind, cause: None }
}