arc_swap/ref_cnt.rs
1use core::mem;
2#[rustversion::since(1.39)]
3use core::pin::Pin;
4use core::ptr;
5
6use crate::imports::{Arc, Rc};
7
8/// A trait describing smart reference counted pointers.
9///
10/// Note that in a way [`Option<Arc<T>>`][Option] is also a smart reference counted pointer, just
11/// one that can hold NULL.
12///
13/// The trait is unsafe, because a wrong implementation will break the [ArcSwapAny]
14/// implementation and lead to UB.
15///
16/// This is not actually expected for downstream crate to implement, this is just means to reuse
17/// code for [Arc] and [`Option<Arc>`][Option] variants. However, it is theoretically possible (if
18/// you have your own [Arc] implementation).
19///
20/// It is also implemented for [Rc], but that is not considered very useful (because the
21/// [ArcSwapAny] is not `Send` or `Sync`, therefore there's very little advantage for it to be
22/// atomic).
23///
24/// # Safety
25///
26/// Aside from the obvious properties (like that incrementing and decrementing a reference count
27/// cancel each out and that having less references tracked than how many things actually point to
28/// the value is fine as long as the count doesn't drop to 0), it also must satisfy that if two
29/// pointers have the same value, they point to the same object. This is specifically not true for
30/// ZSTs, but it is true for `Arc`s of ZSTs, because they have the reference counts just after the
31/// value. It would be fine to point to a type-erased version of the same object, though (if one
32/// could use this trait with unsized types in the first place).
33///
34/// Two types whose pointers can be equal must manage the same reference count, unless they use
35/// different [`TAG`](#associatedconstant.TAG)s. Types sharing the count (eg. `Arc`, `Option<Arc>`
36/// and `Pin<Arc>`) must use the same tag. If `as_ptr` or `into_ptr` can return NULL, that value
37/// must not own any reference count (NULL debts are shared by all the types).
38///
39/// Methods in this trait must not panic nor unwind.
40///
41/// Furthermore, the type should be Pin (eg. if the type is cloned or moved, it should still
42/// point/deref to the same place in memory).
43///
44/// [Arc]: std::sync::Arc
45/// [Rc]: std::rc::Rc
46/// [ArcSwapAny]: crate::ArcSwapAny
47pub unsafe trait RefCnt: Clone {
48 /// The base type the pointer points to.
49 type Base;
50
51 /// Distinguishes debts of types that share addresses but not reference counts (eg. `Arc` and
52 /// `Weak`).
53 ///
54 /// Non-null pointers of this type must have all the bits up to the highest set bit of `TAG`
55 /// zero. Passing a pointer violating that to an `ArcSwapAny` panics.
56 const TAG: usize = 0;
57
58 /// Converts the smart pointer into a raw pointer, without affecting the reference count.
59 ///
60 /// This can be seen as kind of freezing the pointer ‒ it'll be later converted back using
61 /// [`from_ptr`](#method.from_ptr).
62 ///
63 /// The pointer must point to the value stored (and the value must be the same as one returned
64 /// by [`as_ptr`](#method.as_ptr).
65 fn into_ptr(me: Self) -> *mut Self::Base;
66
67 /// Provides a view into the smart pointer as a raw pointer.
68 ///
69 /// This must not affect the reference count ‒ the pointer is only borrowed.
70 fn as_ptr(me: &Self) -> *mut Self::Base;
71
72 /// Converts a raw pointer back into the smart pointer, without affecting the reference count.
73 ///
74 /// This is only called on values previously returned by [`into_ptr`](#method.into_ptr).
75 /// However, it is not guaranteed to be 1:1 relation ‒ `from_ptr` may be called more times than
76 /// `into_ptr` temporarily provided the reference count never drops under 1 during that time
77 /// (the implementation sometimes owes a reference). These extra pointers will either be
78 /// converted back using `into_ptr` or forgotten.
79 ///
80 /// # Safety
81 ///
82 /// This must not be called by code outside of this crate.
83 unsafe fn from_ptr(ptr: *const Self::Base) -> Self;
84
85 /// Increments the reference count by one.
86 ///
87 /// Return the pointer to the inner thing as a side effect.
88 fn inc(me: &Self) -> *mut Self::Base {
89 Self::into_ptr(Self::clone(me))
90 }
91
92 /// Decrements the reference count by one.
93 ///
94 /// Note this is called on a raw pointer (one previously returned by
95 /// [`into_ptr`](#method.into_ptr). This may lead to dropping of the reference count to 0 and
96 /// destruction of the internal pointer.
97 ///
98 /// # Safety
99 ///
100 /// This must not be called by code outside of this crate.
101 unsafe fn dec(ptr: *const Self::Base) {
102 drop(Self::from_ptr(ptr));
103 }
104}
105
106/// Panics if the pointer has the bits needed for `T::TAG` occupied.
107pub(crate) fn check_tag<T: RefCnt>(val: &T) {
108 // All the bits up to the highest set bit of TAG (none for TAG == 0).
109 let mask = (!0usize).checked_shr(T::TAG.leading_zeros()).unwrap_or(0);
110 assert_eq!(
111 T::as_ptr(val) as usize & mask,
112 0,
113 "Pointer not aligned enough for RefCnt::TAG"
114 );
115}
116
117unsafe impl<T> RefCnt for Arc<T> {
118 type Base = T;
119 fn into_ptr(me: Arc<T>) -> *mut T {
120 Arc::into_raw(me) as *mut T
121 }
122 fn as_ptr(me: &Arc<T>) -> *mut T {
123 // Slightly convoluted way to do this, but this avoids stacked borrows violations. The same
124 // intention as
125 //
126 // me as &T as *const T as *mut T
127 //
128 // We first create a "shallow copy" of me - one that doesn't really own its ref count
129 // (that's OK, me _does_ own it, so it can't be destroyed in the meantime).
130 // Then we can use into_raw (which preserves not having the ref count).
131 //
132 // We need to "revert" the changes we did. In current std implementation, the combination
133 // of from_raw and forget is no-op. But formally, into_raw shall be paired with from_raw
134 // and that read shall be paired with forget to properly "close the brackets". In future
135 // versions of STD, these may become something else that's not really no-op (unlikely, but
136 // possible), so we future-proof it a bit.
137
138 // SAFETY: &T cast to *const T will always be aligned, initialised and valid for reads
139 let ptr = Arc::into_raw(unsafe { ptr::read(me) });
140 let ptr = ptr as *mut T;
141
142 // SAFETY: We got the pointer from into_raw just above
143 mem::forget(unsafe { Arc::from_raw(ptr) });
144
145 ptr
146 }
147 unsafe fn from_ptr(ptr: *const T) -> Arc<T> {
148 Arc::from_raw(ptr)
149 }
150}
151
152unsafe impl<T> RefCnt for Rc<T> {
153 type Base = T;
154 fn into_ptr(me: Rc<T>) -> *mut T {
155 Rc::into_raw(me) as *mut T
156 }
157 fn as_ptr(me: &Rc<T>) -> *mut T {
158 // Slightly convoluted way to do this, but this avoids stacked borrows violations. The same
159 // intention as
160 //
161 // me as &T as *const T as *mut T
162 //
163 // We first create a "shallow copy" of me - one that doesn't really own its ref count
164 // (that's OK, me _does_ own it, so it can't be destroyed in the meantime).
165 // Then we can use into_raw (which preserves not having the ref count).
166 //
167 // We need to "revert" the changes we did. In current std implementation, the combination
168 // of from_raw and forget is no-op. But formally, into_raw shall be paired with from_raw
169 // and that read shall be paired with forget to properly "close the brackets". In future
170 // versions of STD, these may become something else that's not really no-op (unlikely, but
171 // possible), so we future-proof it a bit.
172
173 // SAFETY: &T cast to *const T will always be aligned, initialised and valid for reads
174 let ptr = Rc::into_raw(unsafe { ptr::read(me) });
175 let ptr = ptr as *mut T;
176
177 // SAFETY: We got the pointer from into_raw just above
178 mem::forget(unsafe { Rc::from_raw(ptr) });
179
180 ptr
181 }
182 unsafe fn from_ptr(ptr: *const T) -> Rc<T> {
183 Rc::from_raw(ptr)
184 }
185}
186
187unsafe impl<T: RefCnt> RefCnt for Option<T> {
188 type Base = T::Base;
189 const TAG: usize = T::TAG;
190 fn into_ptr(me: Option<T>) -> *mut T::Base {
191 me.map(T::into_ptr).unwrap_or_else(ptr::null_mut)
192 }
193 fn as_ptr(me: &Option<T>) -> *mut T::Base {
194 me.as_ref().map(T::as_ptr).unwrap_or_else(ptr::null_mut)
195 }
196 unsafe fn from_ptr(ptr: *const T::Base) -> Option<T> {
197 if ptr.is_null() {
198 None
199 } else {
200 Some(T::from_ptr(ptr))
201 }
202 }
203}
204
205// Pin is only available since Rust 1.33, but Pin::into_inner is from 1.39.
206#[rustversion::since(1.39)]
207unsafe impl<T> RefCnt for Pin<Arc<T>> {
208 type Base = T;
209
210 fn into_ptr(me: Pin<Arc<T>>) -> *mut T {
211 // SAFETY: We only expose an opaque pointer, which maintains the `Pin` invariant.
212 Arc::into_raw(unsafe { Pin::into_inner_unchecked(me) }) as *mut T
213 }
214
215 fn as_ptr(me: &Pin<Arc<T>>) -> *mut T {
216 // Slightly convoluted way to do this, but this avoids stacked borrows violations. The same
217 // intention as
218 //
219 // me as &T as *const T as *mut T
220 //
221 // We first create a "shallow copy" of me - one that doesn't really own its ref count
222 // (that's OK, me _does_ own it, so it can't be destroyed in the meantime).
223 // Then we can use into_raw (which preserves not having the ref count).
224 //
225 // We need to "revert" the changes we did. In current std implementation, the combination
226 // of from_raw and forget is no-op. But formally, into_raw shall be paired with from_raw
227 // and that read shall be paired with forget to properly "close the brackets". In future
228 // versions of STD, these may become something else that's not really no-op (unlikely, but
229 // possible), so we future-proof it a bit.
230
231 // SAFETY: &T cast to *const T will always be aligned, initialised and valid for reads
232 // We only expose an opaque pointer, which maintains the `Pin` invariant.
233 let me = Arc::into_raw(unsafe { Pin::into_inner_unchecked(ptr::read(me)) });
234 let ptr = me as *mut T;
235
236 // SAFETY: We got the pointer from into_raw just above
237 mem::forget(unsafe { Arc::from_raw(ptr) });
238
239 ptr
240 }
241
242 unsafe fn from_ptr(ptr: *const T) -> Self {
243 // SAFETY: `ptr` came from a previous `{into_ptr,as_ptr}` call, which is pinned.
244 unsafe { Pin::new_unchecked(Arc::from_raw(ptr)) }
245 }
246}
247
248// Pin is only available since Rust 1.33, but Pin::into_inner is from 1.39.
249#[rustversion::since(1.39)]
250unsafe impl<T> RefCnt for Pin<Rc<T>> {
251 type Base = T;
252
253 fn into_ptr(me: Pin<Rc<T>>) -> *mut T {
254 // SAFETY: We only expose an opaque pointer, which maintains the `Pin` invariant.
255 Rc::into_raw(unsafe { Pin::into_inner_unchecked(me) }) as *mut T
256 }
257
258 fn as_ptr(me: &Pin<Rc<T>>) -> *mut T {
259 // Slightly convoluted way to do this, but this avoids stacked borrows violations. The same
260 // intention as
261 //
262 // me as &T as *const T as *mut T
263 //
264 // We first create a "shallow copy" of me - one that doesn't really own its ref count
265 // (that's OK, me _does_ own it, so it can't be destroyed in the meantime).
266 // Then we can use into_raw (which preserves not having the ref count).
267 //
268 // We need to "revert" the changes we did. In current std implementation, the combination
269 // of from_raw and forget is no-op. But formally, into_raw shall be paired with from_raw
270 // and that read shall be paired with forget to properly "close the brackets". In future
271 // versions of STD, these may become something else that's not really no-op (unlikely, but
272 // possible), so we future-proof it a bit.
273
274 // SAFETY: &T cast to *const T will always be aligned, initialised and valid for reads
275 // We only expose an opaque pointer, which maintains the `Pin` invariant.
276 let me = Rc::into_raw(unsafe { Pin::into_inner_unchecked(ptr::read(me)) });
277 let ptr = me as *mut T;
278
279 // SAFETY: We got the pointer from into_raw just above
280 mem::forget(unsafe { Rc::from_raw(ptr) });
281
282 ptr
283 }
284
285 unsafe fn from_ptr(ptr: *const T) -> Self {
286 // SAFETY: `ptr` came from a previous `{into_ptr,as_ptr}` call, which is pinned.
287 unsafe { Pin::new_unchecked(Rc::from_raw(ptr)) }
288 }
289}
290
291#[cfg(test)]
292mod tests {
293 use super::*;
294 use crate::ArcSwapAny;
295
296 #[test]
297 fn ref_cnt_arc() {
298 struct Data(u32);
299
300 let arc = Arc::new(Data(114514));
301 let ptr = RefCnt::as_ptr(&arc);
302 assert_eq!(ptr, RefCnt::into_ptr(arc));
303
304 let arc: Arc<Data> = unsafe { RefCnt::from_ptr(ptr) };
305 assert_eq!(arc.0, 114514);
306 assert_eq!(ptr, RefCnt::as_ptr(&arc));
307 assert_eq!(ptr, RefCnt::into_ptr(arc));
308
309 // Let it drop.
310 let _: Arc<Data> = unsafe { RefCnt::from_ptr(ptr) };
311 }
312
313 /// A pointer into the middle of the `Arc`'s data, so it is odd.
314 #[derive(Clone)]
315 struct Odd(Arc<[u8; 2]>);
316
317 unsafe impl RefCnt for Odd {
318 type Base = [u8; 2];
319 const TAG: usize = 1;
320 fn into_ptr(me: Self) -> *mut [u8; 2] {
321 (RefCnt::into_ptr(me.0) as *mut u8).wrapping_add(1) as *mut [u8; 2]
322 }
323 fn as_ptr(me: &Self) -> *mut [u8; 2] {
324 (RefCnt::as_ptr(&me.0) as *mut u8).wrapping_add(1) as *mut [u8; 2]
325 }
326 unsafe fn from_ptr(ptr: *const [u8; 2]) -> Self {
327 Odd(RefCnt::from_ptr(
328 (ptr as *const u8).wrapping_sub(1) as *const [u8; 2]
329 ))
330 }
331 }
332
333 #[test]
334 #[should_panic(expected = "Pointer not aligned enough")]
335 fn misaligned_tag() {
336 ArcSwapAny::<Odd>::new(Odd(Arc::new([0, 0])));
337 }
338
339 // Pin is only available since Rust 1.33, but Pin::into_inner is from 1.39.
340 #[rustversion::since(1.39)]
341 mod pin {
342 use super::*;
343 use core::marker::PhantomPinned;
344
345 #[test]
346 fn ref_cnt_pin_arc() {
347 struct Unmovable {
348 value: u32,
349 _phantom: PhantomPinned,
350 }
351
352 let pinned = Arc::pin(Unmovable {
353 value: 114514,
354 _phantom: PhantomPinned,
355 });
356 let ptr = RefCnt::as_ptr(&pinned);
357 assert_eq!(ptr, RefCnt::into_ptr(pinned));
358
359 let pinned: Pin<Arc<Unmovable>> = unsafe { RefCnt::from_ptr(ptr) };
360 assert_eq!(pinned.value, 114514);
361 assert_eq!(ptr, RefCnt::as_ptr(&pinned));
362 assert_eq!(ptr, RefCnt::into_ptr(pinned));
363
364 // Let it drop.
365 let _: Pin<Arc<Unmovable>> = unsafe { RefCnt::from_ptr(ptr) };
366 }
367
368 #[test]
369 fn ref_cnt_pin_rc() {
370 struct Unmovable {
371 value: u32,
372 _phantom: PhantomPinned,
373 }
374
375 let pinned = Rc::pin(Unmovable {
376 value: 114514,
377 _phantom: PhantomPinned,
378 });
379 let ptr = RefCnt::as_ptr(&pinned);
380 assert_eq!(ptr, RefCnt::into_ptr(pinned));
381
382 let pinned: Pin<Rc<Unmovable>> = unsafe { RefCnt::from_ptr(ptr) };
383 assert_eq!(pinned.value, 114514);
384 assert_eq!(ptr, RefCnt::as_ptr(&pinned));
385 assert_eq!(ptr, RefCnt::into_ptr(pinned));
386
387 // Let it drop.
388 let _: Pin<Rc<Unmovable>> = unsafe { RefCnt::from_ptr(ptr) };
389 }
390 }
391}