Skip to main content

kafka_client_engine/transaction/initialization/
owner_control.rs

1//! Linear public begin, commit, and abort ownership over one initialized owner.
2
3use std::{fmt, time::Duration};
4
5use kafka_client_core::TransactionEpoch;
6
7use super::{
8    TransactionControlError, TransactionEndAdmissionError, TransactionEndObserver,
9    TransactionLifecycleControlAccepted, TransactionalOwnerHandle,
10    control_error_mapping::{control_error, control_error_kind},
11};
12
13impl TransactionalOwnerHandle {
14    /// Begins one transaction and returns its opaque linear token.
15    pub fn begin_transaction(
16        &mut self,
17    ) -> Result<TransactionBeginAccepted<'_>, TransactionControlError> {
18        let accepted = self.begin().map_err(control_error)?;
19        Ok(TransactionBeginAccepted {
20            transaction: TransactionToken::new(self, accepted.value),
21            wake_failed: accepted.wake_failed,
22        })
23    }
24}
25
26/// Accepted begin ownership plus advisory post-admission wake status.
27#[must_use = "accepted begin retains the sole active transaction token"]
28pub struct TransactionBeginAccepted<'owner> {
29    transaction: TransactionToken<'owner>,
30    wake_failed: bool,
31}
32
33impl<'owner> TransactionBeginAccepted<'owner> {
34    /// Reports that the advisory reactor wake failed after begin acceptance.
35    pub const fn wake_failed(&self) -> bool {
36        self.wake_failed
37    }
38
39    /// Transfers the sole opaque active transaction token.
40    pub fn into_transaction(self) -> TransactionToken<'owner> {
41        self.transaction
42    }
43}
44
45impl fmt::Debug for TransactionBeginAccepted<'_> {
46    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
47        formatter
48            .debug_struct("TransactionBeginAccepted")
49            .field("wake_failed", &self.wake_failed)
50            .finish_non_exhaustive()
51    }
52}
53
54/// Opaque non-clone token for exactly one active transaction epoch.
55#[must_use = "commit, abort, or drop the active transaction token"]
56pub struct TransactionToken<'owner> {
57    pub(super) owner: &'owner mut TransactionalOwnerHandle,
58    pub(super) epoch: TransactionEpoch,
59    armed: bool,
60}
61
62impl<'owner> TransactionToken<'owner> {
63    const fn new(owner: &'owner mut TransactionalOwnerHandle, epoch: TransactionEpoch) -> Self {
64        Self {
65            owner,
66            epoch,
67            armed: true,
68        }
69    }
70
71    /// Attempts to commit this exact transaction.
72    pub fn commit(
73        self,
74        timeout: Duration,
75    ) -> Result<TransactionEndAccepted, TransactionEndAdmissionError<'owner>> {
76        self.end(timeout, TransactionEndIntent::Commit)
77    }
78
79    /// Attempts to abort this exact transaction.
80    pub fn abort(
81        self,
82        timeout: Duration,
83    ) -> Result<TransactionEndAccepted, TransactionEndAdmissionError<'owner>> {
84        self.end(timeout, TransactionEndIntent::Abort)
85    }
86
87    #[cfg(test)]
88    pub(in crate::transaction) const fn epoch(&self) -> TransactionEpoch {
89        self.epoch
90    }
91
92    fn end(
93        mut self,
94        timeout: Duration,
95        intent: TransactionEndIntent,
96    ) -> Result<TransactionEndAccepted, TransactionEndAdmissionError<'owner>> {
97        let lifetime = self.owner.lifetime();
98        let result = match intent {
99            TransactionEndIntent::Commit => self.owner.commit(self.epoch, timeout),
100            TransactionEndIntent::Abort => self.owner.abort(self.epoch, timeout),
101        };
102        match result {
103            Ok(TransactionLifecycleControlAccepted { value, wake_failed }) => {
104                self.armed = false;
105                Ok(TransactionEndAccepted {
106                    observer: TransactionEndObserver::new(value, lifetime),
107                    wake_failed,
108                })
109            }
110            Err(error) => Err(TransactionEndAdmissionError::new(
111                control_error_kind(error),
112                self,
113            )),
114        }
115    }
116}
117
118impl Drop for TransactionToken<'_> {
119    fn drop(&mut self) {
120        if self.armed {
121            self.armed = false;
122            self.owner.lose_owner();
123        }
124    }
125}
126
127impl fmt::Debug for TransactionToken<'_> {
128    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
129        formatter
130            .debug_struct("TransactionToken")
131            .field("transactional_id", &self.owner.transactional_id())
132            .finish_non_exhaustive()
133    }
134}
135
136/// Accepted explicit end ownership plus advisory post-admission wake status.
137#[must_use = "accepted transaction end retains its sole terminal observer"]
138pub struct TransactionEndAccepted {
139    observer: TransactionEndObserver,
140    wake_failed: bool,
141}
142
143impl TransactionEndAccepted {
144    /// Reports that the advisory reactor wake failed after end acceptance.
145    pub const fn wake_failed(&self) -> bool {
146        self.wake_failed
147    }
148
149    /// Transfers the sole runtime-neutral end observer.
150    pub fn into_observer(self) -> TransactionEndObserver {
151        self.observer
152    }
153}
154
155impl fmt::Debug for TransactionEndAccepted {
156    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
157        formatter
158            .debug_struct("TransactionEndAccepted")
159            .field("observer", &self.observer)
160            .field("wake_failed", &self.wake_failed)
161            .finish()
162    }
163}
164
165#[derive(Clone, Copy)]
166enum TransactionEndIntent {
167    Commit,
168    Abort,
169}