Skip to main content

kafka_client_engine/transaction/initialization/
end_observer.rs

1//! Runtime-neutral observation of one explicit transaction end.
2
3use std::{
4    fmt,
5    future::Future,
6    pin::Pin,
7    sync::Arc,
8    task::{Context, Poll},
9};
10
11use kafka_client_core::TransactionLifecycleTerminal;
12
13use crate::completion::{CompletionObserver, CompletionObserverError};
14
15/// Exact terminal consequence of an accepted explicit transaction end.
16#[derive(Clone, Copy, Debug, Eq, PartialEq)]
17pub enum TransactionEndOutcome {
18    /// Kafka committed the transaction.
19    Committed,
20    /// Kafka aborted the transaction.
21    Aborted,
22    /// Transaction execution became permanently unusable.
23    Fatal,
24}
25
26/// Sole named observer for one accepted explicit commit or abort.
27#[must_use = "dropping abandons observation without cancelling the accepted transaction end"]
28pub struct TransactionEndObserver {
29    inner: CompletionObserver<TransactionLifecycleTerminal>,
30    _lifetime: Arc<dyn Send + Sync>,
31}
32
33impl TransactionEndObserver {
34    pub(super) const fn new(
35        inner: CompletionObserver<TransactionLifecycleTerminal>,
36        lifetime: Arc<dyn Send + Sync>,
37    ) -> Self {
38        Self {
39            inner,
40            _lifetime: lifetime,
41        }
42    }
43
44    /// Blocks on the same bounded terminal cell used by [`Future::poll`].
45    pub fn wait(self) -> Result<TransactionEndOutcome, TransactionEndObserverError> {
46        self.inner
47            .wait()
48            .map(translate_terminal)
49            .map_err(observer_error)
50    }
51}
52
53impl Future for TransactionEndObserver {
54    type Output = Result<TransactionEndOutcome, TransactionEndObserverError>;
55
56    fn poll(self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
57        let this = self.get_mut();
58        match Pin::new(&mut this.inner).poll(context) {
59            Poll::Ready(Ok(terminal)) => Poll::Ready(Ok(translate_terminal(terminal))),
60            Poll::Ready(Err(error)) => Poll::Ready(Err(observer_error(error))),
61            Poll::Pending => Poll::Pending,
62        }
63    }
64}
65
66impl fmt::Debug for TransactionEndObserver {
67    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
68        formatter
69            .debug_struct("TransactionEndObserver")
70            .finish_non_exhaustive()
71    }
72}
73
74/// Failure to observe one accepted transaction end terminal.
75#[derive(Clone, Copy, Debug, Eq, PartialEq)]
76pub enum TransactionEndObserverError {
77    /// This linear observer already consumed its terminal.
78    AlreadyObserved,
79    /// The bounded completion generation is no longer live.
80    Stale,
81}
82
83impl fmt::Display for TransactionEndObserverError {
84    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
85        formatter.write_str(match self {
86            Self::AlreadyObserved => "transaction end was already observed",
87            Self::Stale => "transaction end observer is stale",
88        })
89    }
90}
91
92impl std::error::Error for TransactionEndObserverError {}
93
94const fn translate_terminal(terminal: TransactionLifecycleTerminal) -> TransactionEndOutcome {
95    match terminal {
96        TransactionLifecycleTerminal::Committed => TransactionEndOutcome::Committed,
97        TransactionLifecycleTerminal::Aborted => TransactionEndOutcome::Aborted,
98        TransactionLifecycleTerminal::Fatal => TransactionEndOutcome::Fatal,
99    }
100}
101
102const fn observer_error(error: CompletionObserverError) -> TransactionEndObserverError {
103    match error {
104        CompletionObserverError::AlreadyObserved => TransactionEndObserverError::AlreadyObserved,
105        CompletionObserverError::Stale => TransactionEndObserverError::Stale,
106    }
107}