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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
//! Coalesced cross-thread notification for reactor progress.
use std::{fmt, io};
use crate::sync::{
Arc,
atomic::{AtomicU8, Ordering},
spin_loop, yield_now,
};
const IDLE: u8 = 0;
const WAKING: u8 = 1;
const REQUESTED: u8 = 2;
const WAKING_ACKNOWLEDGED: u8 = 3;
const SPIN_LIMIT: usize = 64;
/// Backend capable of interrupting a blocked reactor owner.
pub trait WakeSource: Send + Sync + 'static {
/// Requests that the owner return from its current wait.
///
/// Implementations must be nonblocking, must not panic, and must not call
/// back into the publication or termination path that invoked them.
/// Calandria serializes concurrent requests while this method is in
/// progress so a failed request cannot be mistaken for a successful
/// coalesced wake.
fn wake(&self) -> io::Result<()>;
}
impl<F> WakeSource for F
where
F: Fn() -> io::Result<()> + Send + Sync + 'static,
{
fn wake(&self) -> io::Result<()> {
self()
}
}
/// Cloneable notification handle that coalesces repeated wake requests.
#[derive(Clone)]
pub struct WakeHandle {
shared: Arc<WakeState>,
}
impl WakeHandle {
/// Creates a coalesced handle around one backend wake source.
pub fn new(source: impl WakeSource) -> Self {
Self {
shared: Arc::new(WakeState {
phase: AtomicU8::new(IDLE),
source: Box::new(source),
}),
}
}
/// Requests owner progress.
///
/// Only the first successful request after an acknowledgement reaches the
/// backend. Concurrent callers wait for an in-flight backend request to
/// resolve. If that request fails, one caller may retry rather than
/// returning success for a wake that never occurred.
pub fn wake(&self) -> io::Result<()> {
let mut spins = 0;
loop {
match self.shared.phase.load(Ordering::Acquire) {
REQUESTED => return Ok(()),
IDLE => {
if self
.shared
.phase
.compare_exchange(IDLE, WAKING, Ordering::AcqRel, Ordering::Acquire)
.is_err()
{
continue;
}
return self.finish_wake(self.shared.source.wake());
}
WAKING | WAKING_ACKNOWLEDGED => {
if spins < SPIN_LIMIT {
spins += 1;
spin_loop();
} else {
yield_now();
}
}
_ => panic!("wake phase invariant violated"),
}
}
}
/// Acknowledges that the single owner has observed all work preceding the wake.
///
/// # Contract
///
/// Only the owner of the associated reactor may call this method. A queue
/// must pair acknowledgement with the same lock that linearizes
/// publication, preventing a producer from publishing accepted work
/// between the owner's empty check and this acknowledgement. Calling it
/// from a producer or without that synchronization can strand work.
pub fn acknowledge(&self) {
loop {
match self.shared.phase.load(Ordering::Acquire) {
IDLE | WAKING_ACKNOWLEDGED => return,
REQUESTED => {
if self
.shared
.phase
.compare_exchange(REQUESTED, IDLE, Ordering::AcqRel, Ordering::Acquire)
.is_ok()
{
return;
}
}
WAKING => {
if self
.shared
.phase
.compare_exchange(
WAKING,
WAKING_ACKNOWLEDGED,
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return;
}
}
_ => panic!("wake phase invariant violated"),
}
}
}
/// Returns whether a wake is requested or being issued.
pub fn is_requested(&self) -> bool {
self.shared.phase.load(Ordering::Acquire) != IDLE
}
fn finish_wake(&self, result: io::Result<()>) -> io::Result<()> {
match result {
Ok(()) => {
match self.shared.phase.compare_exchange(
WAKING,
REQUESTED,
Ordering::AcqRel,
Ordering::Acquire,
) {
Ok(_) => {}
Err(WAKING_ACKNOWLEDGED) => {
self.shared.phase.store(IDLE, Ordering::Release);
}
Err(actual) => {
panic!("wake completion invariant violated at phase {actual}")
}
}
Ok(())
}
Err(source) => {
let previous = self.shared.phase.swap(IDLE, Ordering::AcqRel);
assert!(
previous == WAKING || previous == WAKING_ACKNOWLEDGED,
"wake failure invariant violated"
);
Err(source)
}
}
}
}
impl fmt::Debug for WakeHandle {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("WakeHandle")
.field("requested", &self.is_requested())
.finish_non_exhaustive()
}
}
struct WakeState {
phase: AtomicU8,
source: Box<dyn WakeSource>,
}