pub struct Exclusive<T: ?Sized> { /* private fields */ }🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)
Expand description
Exclusive provides mutable access, also referred to as exclusive
access to the underlying value. However, it only permits immutable, or shared
access to the underlying value when that value is Sync.
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<T> for non-Sync T
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.
Source§
Source 🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)
exclusive_wrapper #98407)Gets exclusive access to the underlying value.
Source 🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)
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.
Source 🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)
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.
Source 🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)
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.
Source§
Source§
Source§
Source§
🔬This is a nightly-only experimental API. (pattern #27721)
Associated searcher for this pattern
Source§
🔬This is a nightly-only experimental API. (pattern #27721)
Constructs the associated searcher from
self and the haystack to search in.
Source§
🔬This is a nightly-only experimental API. (pattern #27721)
Checks whether the pattern matches anywhere in the haystack
Source§
🔬This is a nightly-only experimental API. (pattern #27721)
Checks whether the pattern matches at the front of the haystack
Source§
🔬This is a nightly-only experimental API. (pattern #27721)
Removes the pattern from the front of haystack, if it matches.
Source§
🔬This is a nightly-only experimental API. (pattern #27721)
Checks whether the pattern matches at the back of the haystack