numaperf_core/
enforcement.rs

1//! Enforcement level reporting.
2
3/// Reports the actual enforcement level achieved for an operation.
4///
5/// When using soft mode, operations may succeed with reduced guarantees.
6/// This enum allows callers to inspect what level of NUMA policy enforcement
7/// was actually achieved.
8#[derive(Debug, Clone, PartialEq, Eq, Default)]
9pub enum EnforcementLevel {
10    /// The policy is fully enforced.
11    ///
12    /// Memory is bound to the requested nodes, threads are pinned, and
13    /// the kernel guarantees the placement.
14    #[default]
15    Strict,
16
17    /// The policy was applied but is not guaranteed.
18    ///
19    /// The kernel will try to honor the policy, but may move pages or
20    /// threads under memory pressure or other conditions.
21    BestEffort {
22        /// Why strict enforcement was not possible.
23        reason: String,
24    },
25
26    /// No NUMA policy was applied.
27    ///
28    /// The operation succeeded, but no NUMA-specific behavior is in effect.
29    /// Memory may be allocated from any node.
30    None {
31        /// Why no policy could be applied.
32        reason: String,
33    },
34}
35
36impl EnforcementLevel {
37    /// Create a strict enforcement level.
38    #[inline]
39    pub fn strict() -> Self {
40        Self::Strict
41    }
42
43    /// Create a best-effort enforcement level.
44    pub fn best_effort(reason: impl Into<String>) -> Self {
45        Self::BestEffort {
46            reason: reason.into(),
47        }
48    }
49
50    /// Create a none enforcement level.
51    pub fn none(reason: impl Into<String>) -> Self {
52        Self::None {
53            reason: reason.into(),
54        }
55    }
56
57    /// Check if this is strict enforcement.
58    #[inline]
59    pub fn is_strict(&self) -> bool {
60        matches!(self, Self::Strict)
61    }
62
63    /// Check if this is best-effort enforcement.
64    #[inline]
65    pub fn is_best_effort(&self) -> bool {
66        matches!(self, Self::BestEffort { .. })
67    }
68
69    /// Check if no enforcement was applied.
70    #[inline]
71    pub fn is_none(&self) -> bool {
72        matches!(self, Self::None { .. })
73    }
74
75    /// Get the degradation reason, if any.
76    pub fn reason(&self) -> Option<&str> {
77        match self {
78            Self::Strict => None,
79            Self::BestEffort { reason } | Self::None { reason } => Some(reason),
80        }
81    }
82}
83
84impl std::fmt::Display for EnforcementLevel {
85    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
86        match self {
87            Self::Strict => write!(f, "strict"),
88            Self::BestEffort { reason } => write!(f, "best-effort ({})", reason),
89            Self::None { reason } => write!(f, "none ({})", reason),
90        }
91    }
92}
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97
98    #[test]
99    fn test_enforcement_level() {
100        let strict = EnforcementLevel::strict();
101        assert!(strict.is_strict());
102        assert!(!strict.is_best_effort());
103        assert!(strict.reason().is_none());
104
105        let best = EnforcementLevel::best_effort("missing CAP_SYS_ADMIN");
106        assert!(best.is_best_effort());
107        assert_eq!(best.reason(), Some("missing CAP_SYS_ADMIN"));
108
109        let none = EnforcementLevel::none("NUMA not supported");
110        assert!(none.is_none());
111        assert_eq!(none.reason(), Some("NUMA not supported"));
112    }
113
114    #[test]
115    fn test_enforcement_display() {
116        assert_eq!(format!("{}", EnforcementLevel::strict()), "strict");
117        assert_eq!(
118            format!("{}", EnforcementLevel::best_effort("reason")),
119            "best-effort (reason)"
120        );
121    }
122}
numaperf_core/enforcement.rs

numaperf_core/
enforcement.rs
