qubit_cas/observability/
contention_thresholds.rs

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

qubit_cas/observability/
contention_thresholds.rs
