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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

/*******************************************************************************
 *
 *    Copyright (c) 2025 - 2026.
 *    Haixing Hu, Qubit Co. Ltd.
 *
 *    All rights reserved.
 *
 ******************************************************************************/
//! Combined CAS result and execution report.

use std::fmt;

use crate::error::CasError;
use crate::report::CasExecutionReport;
use crate::success::CasSuccess;

/// Public return value for one CAS execution.
///
/// Combines the terminal [`Result`] (`CasSuccess` or [`CasError`]) with the
/// full [`CasExecutionReport`] for observability.
#[derive(Debug, Clone)]
pub struct CasOutcome<T, R, E> {
    /// Terminal success or error.
    result: Result<CasSuccess<T, R>, CasError<T, E>>,
    /// Execution report captured for the flow.
    report: CasExecutionReport,
}

impl<T, R, E> CasOutcome<T, R, E> {
    /// Creates a CAS outcome from a terminal result and execution report.
    ///
    /// # Parameters
    /// - `result`: The terminal [`Result`] from the CAS operation.
    /// - `report`: The full execution report with statistics and timing.
    ///
    /// # Returns
    /// A new [`CasOutcome`] wrapping both values.
    #[inline]
    pub(crate) fn new(
        result: Result<CasSuccess<T, R>, CasError<T, E>>,
        report: CasExecutionReport,
    ) -> Self {
        Self { result, report }
    }

    /// Returns the terminal result.
    ///
    /// # Returns
    /// Reference to the inner [`Result<CasSuccess<T, R>, CasError<T, E>>`].
    #[inline]
    pub fn result(&self) -> &Result<CasSuccess<T, R>, CasError<T, E>> {
        &self.result
    }

    /// Returns the execution report.
    ///
    /// # Returns
    /// Reference to the [`CasExecutionReport`] captured during execution.
    #[inline]
    pub fn report(&self) -> &CasExecutionReport {
        &self.report
    }

    /// Returns whether the execution succeeded.
    ///
    /// # Returns
    /// `true` if the terminal result is [`Ok`].
    #[inline]
    pub fn is_ok(&self) -> bool {
        self.result.is_ok()
    }

    /// Returns whether the execution failed.
    ///
    /// # Returns
    /// `true` if the terminal result is [`Err`].
    #[inline]
    pub fn is_err(&self) -> bool {
        self.result.is_err()
    }

    /// Consumes the outcome and returns its terminal result.
    ///
    /// # Returns
    /// The owned [`Result<CasSuccess<T, R>, CasError<T, E>>`].
    #[inline]
    pub fn into_result(self) -> Result<CasSuccess<T, R>, CasError<T, E>> {
        self.result
    }

    /// Consumes the outcome and returns its parts.
    ///
    /// # Returns
    /// Tuple of the terminal result and the execution report.
    #[inline]
    pub fn into_parts(self) -> (Result<CasSuccess<T, R>, CasError<T, E>>, CasExecutionReport) {
        (self.result, self.report)
    }

    /// Returns the success value or panics with the supplied message.
    ///
    /// This mirrors [`Result::expect`] for call sites that only need the success
    /// value during tests or examples.
    ///
    /// # Parameters
    /// - `message`: Panic message used if the outcome is an error.
    ///
    /// # Returns
    /// The inner [`CasSuccess<T, R>`] on success.
    ///
    /// # Panics
    /// Panics with the given message if the outcome contains an error.
    #[inline]
    pub fn expect(self, message: &str) -> CasSuccess<T, R>
    where
        E: fmt::Debug,
    {
        self.result.expect(message)
    }

    /// Returns the error value or panics with the supplied message.
    ///
    /// This mirrors [`Result::expect_err`] for call sites that only need the
    /// terminal error during tests or examples.
    ///
    /// # Parameters
    /// - `message`: Panic message used if the outcome is a success.
    ///
    /// # Returns
    /// The inner [`CasError<T, E>`] on error.
    ///
    /// # Panics
    /// Panics with the given message if the outcome is successful.
    #[inline]
    pub fn expect_err(self, message: &str) -> CasError<T, E>
    where
        T: fmt::Debug,
        R: fmt::Debug,
    {
        self.result.expect_err(message)
    }
}