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
143
//! Atomic admission state for asynchronous native operations.
//!
//! This state machine is kept separate from the FFI worker so the cancellation
//! and writer admission transition has one compare-and-swap boundary. A
//! cancellation that wins while the request is pending prevents the worker
//! from claiming the request; a cancellation after the worker claims it keeps
//! the outcome ambiguous for mutations.
use std::sync::atomic::{AtomicU8, Ordering};
/// One request's worker-admission state.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[repr(u8)]
pub(crate) enum AdmissionState {
/// No worker has claimed the request and cancellation has not won.
Pending = 0,
/// The worker claimed the request and may transmit it.
Started = 1,
/// Cancellation won before worker admission.
Canceled = 2,
/// The worker claimed the request before cancellation won.
StartedCanceled = 3,
/// The worker completed the operation without cancellation.
Completed = 4,
/// Cancellation won after worker admission and before completion.
CompletedCanceled = 5,
}
impl TryFrom<u8> for AdmissionState {
type Error = ();
fn try_from(value: u8) -> Result<Self, Self::Error> {
match value {
0 => Ok(Self::Pending),
1 => Ok(Self::Started),
2 => Ok(Self::Canceled),
3 => Ok(Self::StartedCanceled),
4 => Ok(Self::Completed),
5 => Ok(Self::CompletedCanceled),
_ => Err(()),
}
}
}
/// Atomic request admission shared by the FFI caller and worker.
pub(crate) struct FfiAdmission {
state: AtomicU8,
}
impl FfiAdmission {
/// Creates an admission in the cancellable pending state.
pub(crate) const fn new() -> Self {
Self {
state: AtomicU8::new(AdmissionState::Pending as u8),
}
}
/// Claims the request for worker execution.
///
/// A `false` result means cancellation won before admission and the worker
/// must drop the queued command without invoking the mutation.
pub(crate) fn try_start(&self) -> bool {
self.state
.compare_exchange(
AdmissionState::Pending as u8,
AdmissionState::Started as u8,
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
}
/// Publishes cancellation and returns the resulting boundary.
pub(crate) fn cancel(&self) -> AdmissionState {
loop {
let current = self.state.load(Ordering::Acquire);
let current_state = AdmissionState::try_from(current)
.expect("FFI request admission state must be a known discriminator");
let next = match current_state {
AdmissionState::Pending => AdmissionState::Canceled,
AdmissionState::Started => AdmissionState::StartedCanceled,
AdmissionState::Canceled
| AdmissionState::StartedCanceled
| AdmissionState::Completed
| AdmissionState::CompletedCanceled => return current_state,
};
if self
.state
.compare_exchange(current, next as u8, Ordering::AcqRel, Ordering::Acquire)
.is_ok()
{
return next;
}
}
}
/// Publishes operation completion and returns the resulting boundary.
///
/// Completion wins over a later cancellation, so a definitive operation
/// result cannot be replaced by a cancellation result after execution has
/// finished. Cancellation that wins before completion remains ambiguous
/// through [`AdmissionState::CompletedCanceled`].
pub(crate) fn complete(&self) -> AdmissionState {
loop {
let current = self.state.load(Ordering::Acquire);
let current_state = AdmissionState::try_from(current)
.expect("FFI request admission state must be a known discriminator");
let next = match current_state {
AdmissionState::Started => AdmissionState::Completed,
AdmissionState::StartedCanceled => AdmissionState::CompletedCanceled,
AdmissionState::Completed | AdmissionState::CompletedCanceled => {
return current_state;
}
AdmissionState::Pending | AdmissionState::Canceled => {
panic!("FFI request completion requires worker admission")
}
};
if self
.state
.compare_exchange(current, next as u8, Ordering::AcqRel, Ordering::Acquire)
.is_ok()
{
return next;
}
}
}
/// Returns the currently published admission state.
pub(crate) fn state(&self) -> AdmissionState {
AdmissionState::try_from(self.state.load(Ordering::Acquire))
.expect("FFI request admission state must be a known discriminator")
}
/// Returns whether cancellation has been published.
pub(crate) fn is_canceled(&self) -> bool {
matches!(
self.state(),
AdmissionState::Canceled
| AdmissionState::StartedCanceled
| AdmissionState::CompletedCanceled
)
}
}