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

#![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(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 }
}