pumas 0.5.0

A power usage monitor for Apple Silicon.
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

//! Type-safe keys for metrics history.
//!
//! This module provides strongly-typed keys for accessing metrics in the history
//! HashMap, replacing stringly-typed keys with an enum for compile-time safety.

/// Identifies a CPU cluster by its kind and index.
///
/// Apple Silicon chips have efficiency (E) and performance (P) clusters.
/// Single-die chips (M1, M2, M3) have one of each, while multi-die chips
/// (M1 Ultra, M2 Ultra) have two of each.
/// Starting with M5 Pro/Max there are also super (S) clusters above performance.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub(crate) struct ClusterId {
    pub kind: ClusterKind,
    pub index: u8,
}

impl ClusterId {
    /// Create an efficiency cluster ID.
    pub const fn efficiency(index: u8) -> Self {
        Self {
            kind: ClusterKind::Efficiency,
            index,
        }
    }

    /// Create a performance cluster ID.
    pub const fn performance(index: u8) -> Self {
        Self {
            kind: ClusterKind::Performance,
            index,
        }
    }

    /// Create a super cluster ID.
    pub const fn super_core(index: u8) -> Self {
        Self {
            kind: ClusterKind::Super,
            index,
        }
    }
}

/// The kind of CPU cluster.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub(crate) enum ClusterKind {
    /// Efficiency cores (E-cluster).
    Efficiency,
    /// Performance cores (P-cluster).
    Performance,
    /// Super cores (S-cluster).
    Super,
}

/// Type-safe key for accessing metrics in the history.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub(crate) enum MetricKey {
    // ─── Cluster metrics ───────────────────────────────────────────────────────
    /// Active ratio for a CPU cluster (0-100%).
    ClusterActivePercent(ClusterId),

    // ─── Per-CPU metrics ───────────────────────────────────────────────────────
    /// Active ratio for a specific CPU core (0-100%).
    CpuActivePercent(u16),
    /// Frequency ratio for a specific CPU core (0-100% of max freq).
    CpuFreqPercent(u16),

    // ─── GPU metrics ───────────────────────────────────────────────────────────
    /// GPU active ratio (0-100%).
    GpuActivePercent,
    /// GPU frequency ratio (0-100% of max freq).
    GpuFreqPercent,

    // ─── ANE metrics ───────────────────────────────────────────────────────────
    /// Apple Neural Engine active ratio (0-100%).
    AneActivePercent,

    // ─── Power consumption ─────────────────────────────────────────────────────
    /// CPU power consumption in watts.
    CpuPowerW,
    /// GPU power consumption in watts.
    GpuPowerW,
    /// ANE power consumption in watts.
    AnePowerW,
    /// Total package power (CPU + GPU + ANE) in watts.
    PackagePowerW,

    // ─── Memory ────────────────────────────────────────────────────────────────
    /// RAM usage in bytes.
    RamUsageBytes,
    /// Swap usage in bytes.
    SwapUsageBytes,
}