#[repr(transparent)]pub struct Exclusive<T> where
T: ?Sized, { /* private fields */ }
Expand description
Exclusive
provides only mutable access, also referred to as exclusive
access to the underlying value. It provides no immutable, or shared
access to the underlying value.
While this may seem not very useful, it allows Exclusive
to unconditionally
implement Sync
. Indeed, the safety requirements of Sync
state that for Exclusive
to be Sync
, it must be sound to share across threads, that is, it must be sound
for &Exclusive
to cross thread boundaries. By design, a &Exclusive
has no API
whatsoever, making it useless, thus harmless, thus memory safe.
Certain constructs like Future
s can only be used with exclusive access,
and are often Send
but not Sync
, so Exclusive
can be used as hint to the
rust compiler that something is Sync
in practice.
Examples
Using a non-Sync
future prevents the wrapping struct from being Sync
use core::cell::Cell;
async fn other() {}
fn assert_sync<T: Sync>(t: T) {}
struct State<F> {
future: F
}
assert_sync(State {
future: async {
let cell = Cell::new(1);
let cell_ref = &cell;
other().await;
let value = cell_ref.get();
}
});
RunExclusive
ensures the struct is Sync
without stripping the future of its
functionality.
#![feature(exclusive_wrapper)]
use core::cell::Cell;
use core::sync::Exclusive;
async fn other() {}
fn assert_sync<T: Sync>(t: T) {}
struct State<F> {
future: Exclusive<F>
}
assert_sync(State {
future: Exclusive::new(async {
let cell = Cell::new(1);
let cell_ref = &cell;
other().await;
let value = cell_ref.get();
})
});
RunParallels with a mutex
In some sense, Exclusive
can be thought of as a compile-time version of
a mutex, as the borrow-checker guarantees that only one &mut
can exist
for any value. This is a parallel with the fact that
&
and &mut
references together can be thought of as a compile-time
version of a read-write lock.
Implementations
sourceimpl<T> Exclusive<T>
impl<T> Exclusive<T>
sourceimpl<T> Exclusive<T> where
T: ?Sized,
impl<T> Exclusive<T> where
T: ?Sized,
sourcepub const fn get_pin_mut(self: Pin<&mut Exclusive<T>>) -> Pin<&mut T>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
pub const fn get_pin_mut(self: Pin<&mut Exclusive<T>>) -> Pin<&mut T>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
Get pinned exclusive access to the underlying value.
Exclusive
is considered to structurally pin the underlying
value, which means unpinned Exclusive
s can produce unpinned
access to the underlying value, but pinned Exclusive
s only
produce pinned access to the underlying value.
sourcepub const fn from_mut(r: &mut T) -> &mut Exclusive<T>ⓘNotable traits for Exclusive<T>impl<T> Future for Exclusive<T> where
T: Future + ?Sized, type Output = <T as Future>::Output;
pub const fn from_mut(r: &mut T) -> &mut Exclusive<T>ⓘNotable traits for Exclusive<T>impl<T> Future for Exclusive<T> where
T: Future + ?Sized, type Output = <T as Future>::Output;
T: Future + ?Sized, type Output = <T as Future>::Output;
Build a mutable references to an Exclusive<T>
from
a mutable reference to a T
. This allows you to skip
building an Exclusive
with Exclusive::new
.
sourcepub const fn from_pin_mut(r: Pin<&mut T>) -> Pin<&mut Exclusive<T>>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
pub const fn from_pin_mut(r: Pin<&mut T>) -> Pin<&mut Exclusive<T>>ⓘNotable traits for Pin<P>impl<P> Future for Pin<P> where
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
P: DerefMut,
<P as Deref>::Target: Future, type Output = <<P as Deref>::Target as Future>::Output;
Build a pinned mutable references to an Exclusive<T>
from
a pinned mutable reference to a T
. This allows you to skip
building an Exclusive
with Exclusive::new
.
Trait Implementations
impl<T> Sync for Exclusive<T> where
T: ?Sized,
Auto Trait Implementations
impl<T: ?Sized> RefUnwindSafe for Exclusive<T> where
T: RefUnwindSafe,
impl<T: ?Sized> Send for Exclusive<T> where
T: Send,
impl<T: ?Sized> Unpin for Exclusive<T> where
T: Unpin,
impl<T: ?Sized> UnwindSafe for Exclusive<T> where
T: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<F> IntoFuture for F where
F: Future,
impl<F> IntoFuture for F where
F: Future,
type IntoFuture = F
type IntoFuture = F
Which kind of future are we turning this into?
sourcefn into_future(self) -> <F as IntoFuture>::IntoFuture
fn into_future(self) -> <F as IntoFuture>::IntoFuture
Creates a future from a value. Read more