qubit-cas 0.2.0

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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

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

use std::time::{Duration, Instant};

use super::{CasExecutionOutcome, CasExecutionReport};

/// Mutable accumulator used internally while one CAS flow is running.
#[derive(Debug, Clone)]
pub(crate) struct CasReportBuilder {
    started_at: Instant,
    conflicts: u32,
    retry_errors: u32,
    aborts: u32,
    timeouts: u32,
}

impl CasReportBuilder {
    /// Starts one report accumulator with the current instant and zeroed counters.
    ///
    /// # Returns
    /// A fresh [`CasReportBuilder`] ready to record statistics during a CAS
    /// execution.
    #[inline]
    pub(crate) fn start() -> Self {
        Self {
            started_at: Instant::now(),
            conflicts: 0,
            retry_errors: 0,
            aborts: 0,
            timeouts: 0,
        }
    }

    /// Returns the start instant captured for this report.
    ///
    /// # Returns
    /// The [`Instant`] when this report builder was started.
    #[inline]
    pub(crate) fn started_at(&self) -> Instant {
        self.started_at
    }

    /// Records one compare-and-swap conflict.
    ///
    /// Increments the internal conflict counter using saturating arithmetic to
    /// prevent overflow.
    #[inline]
    pub(crate) fn record_conflict(&mut self) {
        self.conflicts = self.conflicts.saturating_add(1);
    }

    /// Records one retryable business failure.
    ///
    /// Increments the internal retry error counter using saturating arithmetic.
    #[inline]
    pub(crate) fn record_retry_error(&mut self) {
        self.retry_errors = self.retry_errors.saturating_add(1);
    }

    /// Records one aborting business failure.
    ///
    /// Increments the internal abort counter using saturating arithmetic.
    #[inline]
    pub(crate) fn record_abort(&mut self) {
        self.aborts = self.aborts.saturating_add(1);
    }

    /// Records one async attempt timeout.
    ///
    /// Increments the internal timeout counter using saturating arithmetic.
    #[inline]
    pub(crate) fn record_timeout(&mut self) {
        self.timeouts = self.timeouts.saturating_add(1);
    }

    /// Finishes the accumulator into an immutable report.
    ///
    /// # Parameters
    /// - `attempts_total`: The total number of attempts performed (provided by
    ///   the retry layer).
    /// - `max_attempts`: Configured maximum attempts.
    /// - `max_elapsed`: Configured max elapsed time budget.
    /// - `outcome`: The terminal outcome determined for this execution.
    ///
    /// # Returns
    /// A completed [`CasExecutionReport`] with all statistics and timing
    /// information.
    #[inline]
    pub(crate) fn finish(
        &self,
        attempts_total: u32,
        max_attempts: u32,
        max_elapsed: Option<Duration>,
        outcome: CasExecutionOutcome,
    ) -> CasExecutionReport {
        CasExecutionReport::new(
            attempts_total,
            self.conflicts,
            self.retry_errors,
            self.aborts,
            self.timeouts,
            self.started_at,
            Instant::now(),
            max_attempts,
            max_elapsed,
            outcome,
        )
    }
}