Skip to main content

orbit_atomic/
orbital.rs

1//! The handle: a pointer to one slot and the table that keeps it mapped.
2
3use std::fmt;
4use std::marker::PhantomData;
5use std::ptr::NonNull;
6use std::sync::Arc;
7use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};
8
9use crate::table::{Slot, Table};
10use crate::{OrbitalId, Primitive, Result};
11
12/// One shared value, typed. Cheap to clone; every clone, and every handle
13/// any process opens from the same id, is the same 64 bits.
14///
15/// The operations are those of `std::sync::atomic` and cannot fail. The
16/// memory ordering is not a parameter: every write is sequentially
17/// consistent, which is what lets [`Self::wait`] never miss one.
18pub struct Orbital<T: Primitive> {
19    slot: NonNull<Slot>,
20    id: OrbitalId,
21    /// Keeps the mapping, or the in-memory slot array, that `slot` points
22    /// into.
23    table: Arc<Table>,
24    _type: PhantomData<T>,
25}
26
27// SAFETY: the slot is atomics in memory the handle keeps alive.
28unsafe impl<T: Primitive> Send for Orbital<T> {}
29// SAFETY: as above.
30unsafe impl<T: Primitive> Sync for Orbital<T> {}
31
32impl<T: Primitive> Clone for Orbital<T> {
33    fn clone(&self) -> Self {
34        Self {
35            slot: self.slot,
36            id: self.id,
37            table: Arc::clone(&self.table),
38            _type: PhantomData,
39        }
40    }
41}
42
43impl<T: Primitive> fmt::Debug for Orbital<T> {
44    fn fmt(
45        &self,
46        f: &mut fmt::Formatter<'_>,
47    ) -> fmt::Result {
48        f.debug_tuple("Orbital").field(&self.id).finish()
49    }
50}
51
52impl<T: Primitive> Orbital<T> {
53    pub(crate) fn new(
54        slot: NonNull<Slot>,
55        id: OrbitalId,
56        table: Arc<Table>,
57    ) -> Self {
58        Self { slot, id, table, _type: PhantomData }
59    }
60
61    #[inline]
62    fn slot(&self) -> &Slot {
63        // SAFETY: resolved when the handle was made, inside memory that
64        // `table` keeps mapped for as long as the handle lives.
65        unsafe { self.slot.as_ref() }
66    }
67
68    /// One write: the value word, then whether anyone waits.
69    #[inline]
70    fn write<R>(
71        &self,
72        operation: impl FnOnce(&AtomicU64) -> R,
73    ) -> R {
74        let slot = self.slot();
75        let result = operation(&slot.value);
76        slot.wake.changed();
77        result
78    }
79
80    /// The address to hand to another process.
81    pub fn id(&self) -> OrbitalId {
82        self.id
83    }
84
85    #[inline]
86    pub fn load(&self) -> T {
87        T::from_word(self.slot().value.load(Ordering::Acquire))
88    }
89
90    #[inline]
91    pub fn store(
92        &self,
93        value: T,
94    ) {
95        self.write(|word| word.store(value.into_word(), Ordering::SeqCst));
96    }
97
98    /// Replace the value and return what it was.
99    #[inline]
100    pub fn swap(
101        &self,
102        value: T,
103    ) -> T {
104        T::from_word(
105            self.write(|word| word.swap(value.into_word(), Ordering::SeqCst)),
106        )
107    }
108
109    /// Store `new` only if the value is still `current`: `Ok(previous)`
110    /// when it was, `Err(actual)` when it held something else. An `f64` is
111    /// compared by its bits, so `0.0` is not `-0.0` and a NaN equals only
112    /// the same NaN.
113    #[inline]
114    pub fn compare_exchange(
115        &self,
116        current: T,
117        new: T,
118    ) -> Result<T, T> {
119        let slot = self.slot();
120        let exchanged = slot.value.compare_exchange(
121            current.into_word(),
122            new.into_word(),
123            Ordering::SeqCst,
124            Ordering::SeqCst,
125        );
126        if exchanged.is_ok() {
127            slot.wake.changed();
128        }
129        exchanged.map(T::from_word).map_err(T::from_word)
130    }
131
132    /// Park until the value is no longer `current`, then return what it
133    /// is. Returns at once when it already differs.
134    ///
135    /// Coalescing: any number of writes while parked are one wake, and a
136    /// value that left `current` and came back before the caller looked is
137    /// no change. An `f64` is compared by its bits. Blocking; an async
138    /// runtime runs it where blocking is allowed.
139    pub fn wait(
140        &self,
141        current: T,
142    ) -> Result<T> {
143        let slot = self.slot();
144        let current = current.into_word();
145        loop {
146            let now = slot.value.load(Ordering::SeqCst);
147            if now != current {
148                return Ok(T::from_word(now));
149            }
150            slot.wake
151                .wait_if(|| slot.value.load(Ordering::SeqCst) == current)?;
152        }
153    }
154
155    /// [`Self::wait`], which a second word can end: `Ok(Some(value))` is a
156    /// change, `Ok(None)` is the interrupt.
157    ///
158    /// This is not a timeout; nothing here measures time. The canceller
159    /// sets `interrupt` and then calls [`Self::notify`], in that order, on
160    /// any handle to the same value.
161    pub fn wait_until(
162        &self,
163        current: T,
164        interrupt: &AtomicBool,
165    ) -> Result<Option<T>> {
166        let slot = self.slot();
167        let current = current.into_word();
168        loop {
169            if interrupt.load(Ordering::SeqCst) {
170                return Ok(None);
171            }
172            let now = slot.value.load(Ordering::SeqCst);
173            if now != current {
174                return Ok(Some(T::from_word(now)));
175            }
176            slot.wake.wait_if(|| {
177                slot.value.load(Ordering::SeqCst) == current
178                    && !interrupt.load(Ordering::SeqCst)
179            })?;
180        }
181    }
182
183    /// Wake everyone parked on this value without writing to it. A waiter
184    /// whose value has not changed and whose interrupt is not set parks
185    /// again.
186    pub fn notify(&self) {
187        self.slot().wake.notify();
188    }
189}
190
191macro_rules! integer {
192    ($type:ty, $atomic:ty) => {
193        impl Orbital<$type> {
194            #[inline]
195            fn integer<R>(
196                &self,
197                operation: impl FnOnce(&$atomic) -> R,
198            ) -> R {
199                // SAFETY: the value word is a live, aligned 64-bit atomic,
200                // and both atomic integer types share its representation.
201                self.write(|word| unsafe {
202                    operation(<$atomic>::from_ptr(word.as_ptr().cast()))
203                })
204            }
205
206            /// Add, wrapping on overflow, and return the previous value.
207            #[inline]
208            pub fn fetch_add(
209                &self,
210                value: $type,
211            ) -> $type {
212                self.integer(|word| word.fetch_add(value, Ordering::SeqCst))
213            }
214
215            /// Subtract, wrapping on overflow, and return the previous
216            /// value.
217            #[inline]
218            pub fn fetch_sub(
219                &self,
220                value: $type,
221            ) -> $type {
222                self.integer(|word| word.fetch_sub(value, Ordering::SeqCst))
223            }
224
225            #[inline]
226            pub fn fetch_and(
227                &self,
228                value: $type,
229            ) -> $type {
230                self.integer(|word| word.fetch_and(value, Ordering::SeqCst))
231            }
232
233            #[inline]
234            pub fn fetch_or(
235                &self,
236                value: $type,
237            ) -> $type {
238                self.integer(|word| word.fetch_or(value, Ordering::SeqCst))
239            }
240
241            #[inline]
242            pub fn fetch_xor(
243                &self,
244                value: $type,
245            ) -> $type {
246                self.integer(|word| word.fetch_xor(value, Ordering::SeqCst))
247            }
248
249            /// Keep the larger of the two and return the previous value.
250            #[inline]
251            pub fn fetch_max(
252                &self,
253                value: $type,
254            ) -> $type {
255                self.integer(|word| word.fetch_max(value, Ordering::SeqCst))
256            }
257
258            /// Keep the smaller of the two and return the previous value.
259            #[inline]
260            pub fn fetch_min(
261                &self,
262                value: $type,
263            ) -> $type {
264                self.integer(|word| word.fetch_min(value, Ordering::SeqCst))
265            }
266        }
267    };
268}
269
270integer!(i64, AtomicI64);
271integer!(u64, AtomicU64);
272
273impl Orbital<f64> {
274    /// Add and return the previous value. A compare-and-swap loop: floats
275    /// have no fetch-add of their own.
276    pub fn fetch_add(
277        &self,
278        value: f64,
279    ) -> f64 {
280        f64::from_bits(self.write(|word| {
281            word.update(Ordering::SeqCst, Ordering::SeqCst, |bits| {
282                (f64::from_bits(bits) + value).to_bits()
283            })
284        }))
285    }
286}
287
288impl Orbital<bool> {
289    #[inline]
290    pub fn fetch_and(
291        &self,
292        value: bool,
293    ) -> bool {
294        self.write(|word| word.fetch_and(u64::from(value), Ordering::SeqCst))
295            != 0
296    }
297
298    #[inline]
299    pub fn fetch_or(
300        &self,
301        value: bool,
302    ) -> bool {
303        self.write(|word| word.fetch_or(u64::from(value), Ordering::SeqCst))
304            != 0
305    }
306
307    #[inline]
308    pub fn fetch_xor(
309        &self,
310        value: bool,
311    ) -> bool {
312        self.write(|word| word.fetch_xor(u64::from(value), Ordering::SeqCst))
313            != 0
314    }
315}