qubit_cas/observability/
contention_thresholds.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9
10/// Thresholds used to classify one execution as hotly contended.
11#[derive(Debug, Clone, Copy, PartialEq)]
12pub struct ContentionThresholds {
13    /// Minimum attempt count before the ratio is meaningful.
14    min_attempts: u32,
15    /// Minimum raw conflict count.
16    min_conflicts: u32,
17    /// Minimum conflict ratio.
18    conflict_ratio: f64,
19}
20
21impl ContentionThresholds {
22    /// Creates contention thresholds from raw values.
23    ///
24    /// The conflict ratio is clamped to `[0.0, 1.0]`.
25    ///
26    /// # Parameters
27    /// - `min_attempts`: Minimum attempts before ratio check is meaningful.
28    /// - `min_conflicts`: Minimum absolute conflicts required.
29    /// - `conflict_ratio`: Minimum conflict ratio (clamped to [0.0, 1.0]).
30    ///
31    /// # Returns
32    /// A normalized [`ContentionThresholds`] value.
33    #[inline]
34    pub fn new(min_attempts: u32, min_conflicts: u32, conflict_ratio: f64) -> Self {
35        Self {
36            min_attempts,
37            min_conflicts,
38            conflict_ratio: conflict_ratio.clamp(0.0, 1.0),
39        }
40    }
41
42    /// Returns the minimum attempt count.
43    ///
44    /// # Returns
45    /// Minimum number of attempts before a ratio is considered meaningful.
46    #[inline]
47    pub fn min_attempts(&self) -> u32 {
48        self.min_attempts
49    }
50
51    /// Returns the minimum conflict count.
52    ///
53    /// # Returns
54    /// Minimum raw number of conflicts required to be considered hot.
55    #[inline]
56    pub fn min_conflicts(&self) -> u32 {
57        self.min_conflicts
58    }
59
60    /// Returns the minimum conflict ratio.
61    ///
62    /// # Returns
63    /// Minimum ratio of conflicts to total attempts.
64    #[inline]
65    pub fn conflict_ratio(&self) -> f64 {
66        self.conflict_ratio
67    }
68}
69
70impl Default for ContentionThresholds {
71    /// Returns the recommended high-contention threshold.
72    #[inline]
73    fn default() -> Self {
74        Self::new(3, 1, 0.30)
75    }
76}
qubit_cas/observability/contention_thresholds.rs

qubit_cas/observability/
contention_thresholds.rs
