1 //! Defines [`Exclusive`].
4 use core::future::Future;
6 use core::task::{Context, Poll};
8 /// `Exclusive` provides only _mutable_ access, also referred to as _exclusive_
9 /// access to the underlying value. It provides no _immutable_, or _shared_
10 /// access to the underlying value.
12 /// While this may seem not very useful, it allows `Exclusive` to _unconditionally_
13 /// implement [`Sync`]. Indeed, the safety requirements of `Sync` state that for `Exclusive`
14 /// to be `Sync`, it must be sound to _share_ across threads, that is, it must be sound
15 /// for `&Exclusive` to cross thread boundaries. By design, a `&Exclusive` has no API
16 /// whatsoever, making it useless, thus harmless, thus memory safe.
18 /// Certain constructs like [`Future`]s can only be used with _exclusive_ access,
19 /// and are often `Send` but not `Sync`, so `Exclusive` can be used as hint to the
20 /// rust compiler that something is `Sync` in practice.
23 /// Using a non-`Sync` future prevents the wrapping struct from being `Sync`
25 /// use core::cell::Cell;
27 /// async fn other() {}
28 /// fn assert_sync<T: Sync>(t: T) {}
33 /// assert_sync(State {
35 /// let cell = Cell::new(1);
36 /// let cell_ref = &cell;
38 /// let value = cell_ref.get();
43 /// `Exclusive` ensures the struct is `Sync` without stripping the future of its
46 /// #![feature(exclusive_wrapper)]
47 /// use core::cell::Cell;
48 /// use core::sync::Exclusive;
50 /// async fn other() {}
51 /// fn assert_sync<T: Sync>(t: T) {}
53 /// future: Exclusive<F>
56 /// assert_sync(State {
57 /// future: Exclusive::new(async {
58 /// let cell = Cell::new(1);
59 /// let cell_ref = &cell;
61 /// let value = cell_ref.get();
66 /// ## Parallels with a mutex
67 /// In some sense, `Exclusive` can be thought of as a _compile-time_ version of
68 /// a mutex, as the borrow-checker guarantees that only one `&mut` can exist
69 /// for any value. This is a parallel with the fact that
70 /// `&` and `&mut` references together can be thought of as a _compile-time_
71 /// version of a read-write lock.
74 /// [`Sync`]: core::marker::Sync
75 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
76 #[doc(alias = "SyncWrapper")]
77 #[doc(alias = "SyncCell")]
78 #[doc(alias = "Unique")]
79 // `Exclusive` can't have `PartialOrd`, `Clone`, etc. impls as they would
80 // use `&` access to the inner value, violating the `Sync` impl's safety
84 pub struct Exclusive<T: ?Sized> {
88 // See `Exclusive`'s docs for justification.
89 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
90 unsafe impl<T: ?Sized> Sync for Exclusive<T> {}
92 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
93 impl<T: ?Sized> fmt::Debug for Exclusive<T> {
94 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
95 f.debug_struct("Exclusive").finish_non_exhaustive()
99 impl<T: Sized> Exclusive<T> {
100 /// Wrap a value in an `Exclusive`
101 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
104 pub const fn new(t: T) -> Self {
108 /// Unwrap the value contained in the `Exclusive`
109 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
112 pub const fn into_inner(self) -> T {
117 impl<T: ?Sized> Exclusive<T> {
118 /// Get exclusive access to the underlying value.
119 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
122 pub const fn get_mut(&mut self) -> &mut T {
126 /// Get pinned exclusive access to the underlying value.
128 /// `Exclusive` is considered to _structurally pin_ the underlying
129 /// value, which means _unpinned_ `Exclusive`s can produce _unpinned_
130 /// access to the underlying value, but _pinned_ `Exclusive`s only
131 /// produce _pinned_ access to the underlying value.
132 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
135 pub const fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> {
136 // SAFETY: `Exclusive` can only produce `&mut T` if itself is unpinned
137 // `Pin::map_unchecked_mut` is not const, so we do this conversion manually
138 unsafe { Pin::new_unchecked(&mut self.get_unchecked_mut().inner) }
141 /// Build a _mutable_ references to an `Exclusive<T>` from
142 /// a _mutable_ reference to a `T`. This allows you to skip
143 /// building an `Exclusive` with [`Exclusive::new`].
144 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
147 pub const fn from_mut(r: &'_ mut T) -> &'_ mut Exclusive<T> {
148 // SAFETY: repr is ≥ C, so refs have the same layout; and `Exclusive` properties are `&mut`-agnostic
149 unsafe { &mut *(r as *mut T as *mut Exclusive<T>) }
152 /// Build a _pinned mutable_ references to an `Exclusive<T>` from
153 /// a _pinned mutable_ reference to a `T`. This allows you to skip
154 /// building an `Exclusive` with [`Exclusive::new`].
155 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
158 pub const fn from_pin_mut(r: Pin<&'_ mut T>) -> Pin<&'_ mut Exclusive<T>> {
159 // SAFETY: `Exclusive` can only produce `&mut T` if itself is unpinned
160 // `Pin::map_unchecked_mut` is not const, so we do this conversion manually
161 unsafe { Pin::new_unchecked(Self::from_mut(r.get_unchecked_mut())) }
165 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
166 impl<T> From<T> for Exclusive<T> {
168 fn from(t: T) -> Self {
173 #[unstable(feature = "exclusive_wrapper", issue = "98407")]
174 impl<T: Future + ?Sized> Future for Exclusive<T> {
175 type Output = T::Output;
177 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
178 self.get_pin_mut().poll(cx)