qubit_cas/fast/
fast_cas_success.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//! Successful fast compare-and-swap results.
11
12#[derive(Debug, Clone, Copy, Eq, PartialEq)]
13enum FastCasSuccessKind {
14    Updated,
15    Finished,
16}
17
18/// Successful [`crate::FastCas`] result.
19#[derive(Debug, Clone, Copy, Eq, PartialEq)]
20pub struct FastCasSuccess<R> {
21    /// State observed by the successful attempt.
22    previous: usize,
23    /// State after completion.
24    current: usize,
25    /// Business output.
26    output: R,
27    /// Number of attempts consumed.
28    attempts: u32,
29    /// Decision path that produced the success.
30    kind: FastCasSuccessKind,
31}
32
33impl<R> FastCasSuccess<R> {
34    /// Creates a successful update result.
35    ///
36    /// # Parameters
37    /// - `previous`: State observed by the successful attempt.
38    /// - `current`: State after completion.
39    /// - `output`: Business output.
40    /// - `attempts`: Number of attempts consumed.
41    ///
42    /// # Returns
43    /// A successful update result value.
44    #[inline]
45    pub(crate) const fn updated(previous: usize, current: usize, output: R, attempts: u32) -> Self {
46        Self {
47            previous,
48            current,
49            output,
50            attempts,
51            kind: FastCasSuccessKind::Updated,
52        }
53    }
54
55    /// Creates a successful finish result.
56    ///
57    /// # Parameters
58    /// - `current`: State observed when the operation finished.
59    /// - `output`: Business output.
60    /// - `attempts`: Number of attempts consumed.
61    ///
62    /// # Returns
63    /// A successful finish result value.
64    #[inline]
65    pub(crate) const fn finished(current: usize, output: R, attempts: u32) -> Self {
66        Self {
67            previous: current,
68            current,
69            output,
70            attempts,
71            kind: FastCasSuccessKind::Finished,
72        }
73    }
74
75    /// Returns the state observed before successful completion.
76    ///
77    /// # Returns
78    /// The state code read by the successful attempt.
79    #[inline]
80    pub const fn previous(&self) -> usize {
81        self.previous
82    }
83
84    /// Returns the state after completion.
85    ///
86    /// # Returns
87    /// The installed state for updates, or [`previous`](Self::previous) for
88    /// finishes.
89    #[inline]
90    pub const fn current(&self) -> usize {
91        self.current
92    }
93
94    /// Returns a shared reference to the business output.
95    ///
96    /// # Returns
97    /// The output produced by the operation.
98    #[inline]
99    pub const fn output(&self) -> &R {
100        &self.output
101    }
102
103    /// Consumes this result and returns the business output.
104    ///
105    /// # Returns
106    /// The output produced by the operation.
107    #[inline]
108    pub fn into_output(self) -> R {
109        self.output
110    }
111
112    /// Returns the number of attempts consumed.
113    ///
114    /// # Returns
115    /// Number of attempts executed by the operation.
116    #[inline]
117    pub const fn attempts(&self) -> u32 {
118        self.attempts
119    }
120
121    /// Tests whether this success came from an update decision.
122    ///
123    /// # Returns
124    /// `true` when the operation successfully executed an update decision,
125    /// even if the installed state equals the previously observed state.
126    #[inline]
127    pub const fn is_updated(&self) -> bool {
128        matches!(self.kind, FastCasSuccessKind::Updated)
129    }
130
131    /// Tests whether this success came from a finish decision.
132    ///
133    /// # Returns
134    /// `true` when the operation completed through a finish decision.
135    #[inline]
136    pub const fn is_finished(&self) -> bool {
137        matches!(self.kind, FastCasSuccessKind::Finished)
138    }
139}
qubit_cas/fast/fast_cas_success.rs

qubit_cas/fast/
fast_cas_success.rs
