pub struct Exclusive<T: ?Sized> { /* private fields */ }
exclusive_wrapper
#98407)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();
}
});
Exclusive
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();
})
});
§Parallels 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§
source§impl<T: ?Sized> Exclusive<T>
impl<T: ?Sized> Exclusive<T>
sourcepub const fn get_mut(&mut self) -> &mut T
🔬This is a nightly-only experimental API. (exclusive_wrapper
#98407)
pub const fn get_mut(&mut self) -> &mut T
exclusive_wrapper
#98407)Gets exclusive access to the underlying value.
sourcepub const fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T>
🔬This is a nightly-only experimental API. (exclusive_wrapper
#98407)
pub const fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T>
exclusive_wrapper
#98407)Gets 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> ⓘ
🔬This is a nightly-only experimental API. (exclusive_wrapper
#98407)
pub const fn from_mut(r: &mut T) -> &mut Exclusive<T> ⓘ
exclusive_wrapper
#98407)Build a mutable reference 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>>
🔬This is a nightly-only experimental API. (exclusive_wrapper
#98407)
pub const fn from_pin_mut(r: Pin<&mut T>) -> Pin<&mut Exclusive<T>>
exclusive_wrapper
#98407)Build a pinned mutable reference 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§
source§impl<R, G> Coroutine<R> for Exclusive<G>
impl<R, G> Coroutine<R> for Exclusive<G>
source§type Yield = <G as Coroutine<R>>::Yield
type Yield = <G as Coroutine<R>>::Yield
coroutine_trait
#43122)impl<T: ?Sized> Sync for Exclusive<T>
Auto Trait Implementations§
impl<T> Freeze for Exclusive<T>
impl<T> RefUnwindSafe for Exclusive<T>where
T: RefUnwindSafe + ?Sized,
impl<T> Send for Exclusive<T>
impl<T> Unpin for Exclusive<T>
impl<T> UnwindSafe for Exclusive<T>where
T: UnwindSafe + ?Sized,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<F> IntoFuture for Fwhere
F: Future,
impl<F> IntoFuture for Fwhere
F: Future,
source§type IntoFuture = F
type IntoFuture = F
source§fn into_future(self) -> <F as IntoFuture>::IntoFuture
fn into_future(self) -> <F as IntoFuture>::IntoFuture
source§impl<F> Pattern for F
impl<F> Pattern for F
source§type Searcher<'a> = CharPredicateSearcher<'a, F>
type Searcher<'a> = CharPredicateSearcher<'a, F>
pattern
#27721)source§fn into_searcher<'a>(self, haystack: &'a str) -> CharPredicateSearcher<'a, F>
fn into_searcher<'a>(self, haystack: &'a str) -> CharPredicateSearcher<'a, F>
pattern
#27721)self
and the haystack
to search in.source§fn is_contained_in<'a>(self, haystack: &'a str) -> bool
fn is_contained_in<'a>(self, haystack: &'a str) -> bool
pattern
#27721)source§fn is_prefix_of<'a>(self, haystack: &'a str) -> bool
fn is_prefix_of<'a>(self, haystack: &'a str) -> bool
pattern
#27721)source§fn strip_prefix_of<'a>(self, haystack: &'a str) -> Option<&'a str>
fn strip_prefix_of<'a>(self, haystack: &'a str) -> Option<&'a str>
pattern
#27721)source§fn is_suffix_of<'a>(self, haystack: &'a str) -> boolwhere
CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,
fn is_suffix_of<'a>(self, haystack: &'a str) -> boolwhere
CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,
pattern
#27721)source§fn strip_suffix_of<'a>(self, haystack: &'a str) -> Option<&'a str>where
CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,
fn strip_suffix_of<'a>(self, haystack: &'a str) -> Option<&'a str>where
CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,
pattern
#27721)