pub struct Exclusive<T>where
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 Futures 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> Exclusive<T>
impl<T> Exclusive<T>
Sourcepub const fn new(t: T) -> Exclusive<T> โ
๐ฌThis is a nightly-only experimental API. (exclusive_wrapper #98407)
pub const fn new(t: T) -> Exclusive<T> โ
exclusive_wrapper #98407)Wrap a value in an Exclusive
Sourcepub const fn into_inner(self) -> T
๐ฌThis is a nightly-only experimental API. (exclusive_wrapper #98407)
pub const fn into_inner(self) -> T
exclusive_wrapper #98407)Unwrap the value contained in the Exclusive
Sourceยงimpl<T> Exclusive<T>where
T: ?Sized,
impl<T> Exclusive<T>where
T: ?Sized,
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 Exclusive<T>>) -> Pin<&mut T>
๐ฌThis is a nightly-only experimental API. (exclusive_wrapper #98407)
pub const fn get_pin_mut(self: Pin<&mut Exclusive<T>>) -> 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 Exclusives can produce unpinned
access to the underlying value, but pinned Exclusives 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> Sync for Exclusive<T>where
T: ?Sized,
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)Sourceยงfn as_utf8_pattern(&self) -> Option<Utf8Pattern<'_>>
fn as_utf8_pattern(&self) -> Option<Utf8Pattern<'_>>
pattern #27721)