qubit-cas 0.3.3

Typed compare-and-swap executor with retry-aware conflict handling
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

/*******************************************************************************
 *
 *    Copyright (c) 2025 - 2026.
 *    Haixing Hu, Qubit Co. Ltd.
 *
 *    All rights reserved.
 *
 ******************************************************************************/

use std::time::Duration;

/// Human-readable profile for one CAS strategy.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CasStrategyProfile {
    /// Maximum attempts used by the strategy.
    max_attempts: u32,
    /// Maximum cumulative user operation elapsed-time budget.
    max_operation_elapsed: Duration,
    /// Optional monotonic total retry-flow elapsed-time budget.
    max_total_elapsed: Option<Duration>,
    /// Conflict ratio at which callers should consider this profile suitable.
    target_conflict_ratio: f64,
    /// Whether the strategy uses retry backoff.
    uses_backoff: bool,
}

impl CasStrategyProfile {
    /// Creates a strategy profile from static preset values.
    #[inline]
    pub(crate) const fn new(
        max_attempts: u32,
        max_operation_elapsed: Duration,
        max_total_elapsed: Option<Duration>,
        target_conflict_ratio: f64,
        uses_backoff: bool,
    ) -> Self {
        Self {
            max_attempts,
            max_operation_elapsed,
            max_total_elapsed,
            target_conflict_ratio,
            uses_backoff,
        }
    }

    /// Returns the maximum attempts used by the strategy.
    ///
    /// # Returns
    /// Maximum number of attempts (including initial) for this strategy.
    #[inline]
    pub fn max_attempts(&self) -> u32 {
        self.max_attempts
    }

    /// Returns the maximum cumulative user operation elapsed-time budget.
    ///
    /// # Returns
    /// User operation time budget for the entire CAS flow.
    #[inline]
    pub fn max_operation_elapsed(&self) -> Duration {
        self.max_operation_elapsed
    }

    /// Returns the optional monotonic total retry-flow elapsed-time budget.
    ///
    /// # Returns
    /// `Some(Duration)` when the strategy caps whole-flow time (including retry
    /// sleeps), or `None` when only the operation-time budget applies.
    #[inline]
    pub fn max_total_elapsed(&self) -> Option<Duration> {
        self.max_total_elapsed
    }

    /// Returns the target conflict ratio for this strategy profile.
    ///
    /// # Returns
    /// The conflict ratio at which this strategy is recommended.
    #[inline]
    pub fn target_conflict_ratio(&self) -> f64 {
        self.target_conflict_ratio
    }

    /// Returns whether this profile uses retry backoff.
    ///
    /// # Returns
    /// `true` for strategies that insert delays between retries.
    #[inline]
    pub fn uses_backoff(&self) -> bool {
        self.uses_backoff
    }
}