Struct Exclusive 

pub struct Exclusive<T: ?Sized> { /* private fields */ }

🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)

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.

Implementations

impl<T: Sized> Exclusive<T>

pub const fn new(t: T) -> Self

🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)

Wrap a value in an Exclusive

pub const fn into_inner(self) -> T

🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)

Unwrap the value contained in the Exclusive

impl<T: ?Sized> Exclusive<T>

pub const fn get_mut(&mut self) -> &mut T

🔬This is a nightly-only experimental API. (exclusive_wrapper #98407)

Gets exclusive access to the underlying value.

pub const fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T>

🔬This is a nightly-only experimental API. (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.

pub const fn from_mut(r: &mut T) -> &mut Exclusive<T>

🔬This is a nightly-only experimental API. (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.

pub const fn from_pin_mut(r: Pin<&mut T>) -> Pin<&mut Exclusive<T>>

🔬This is a nightly-only experimental API. (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

impl<T> AsRef<T> for Exclusive<T>

where T: Sync + ?Sized,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Clone for Exclusive<T>

where T: Sync + Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

where Self:,

Performs copy-assignment from source.

impl<R, G> Coroutine<R> for Exclusive<G>

where G: Coroutine<R> + ?Sized,

type Yield = <G as Coroutine<R>>::Yield

🔬This is a nightly-only experimental API. (coroutine_trait #43122)

The type of value this coroutine yields.

type Return = <G as Coroutine<R>>::Return

🔬This is a nightly-only experimental API. (coroutine_trait #43122)

The type of value this coroutine returns.

fn resume( self: Pin<&mut Self>, arg: R, ) -> CoroutineState<Self::Yield, Self::Return>

🔬This is a nightly-only experimental API. (coroutine_trait #43122)

Resumes the execution of this coroutine.

impl<T: ?Sized> Debug for Exclusive<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T: Default + ?Sized> Default for Exclusive<T>

fn default() -> Exclusive<T>

Returns the “default value” for a type.

impl<F, Args> Fn<Args> for Exclusive<F>

where F: Sync + Fn<Args>, Args: Tuple,

extern "rust-call" fn call(&self, args: Args) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits #29625)

Performs the call operation.

impl<F, Args> FnMut<Args> for Exclusive<F>

where F: FnMut<Args>, Args: Tuple,

extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits #29625)

Performs the call operation.

impl<F, Args> FnOnce<Args> for Exclusive<F>

where F: FnOnce<Args>, Args: Tuple,

type Output = <F as FnOnce<Args>>::Output

The returned type after the call operator is used.

extern "rust-call" fn call_once(self, args: Args) -> Self::Output

🔬This is a nightly-only experimental API. (fn_traits #29625)

Performs the call operation.

impl<T> From<T> for Exclusive<T>

fn from(t: T) -> Self

Converts to this type from the input type.

impl<T> Future for Exclusive<T>

where T: Future + ?Sized,

type Output = <T as Future>::Output

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T> Hash for Exclusive<T>

where T: Sync + Hash + ?Sized,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H: Hasher>(data: &[Self], state: &mut H)

where Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for Exclusive<T>

where T: Sync + Ord + ?Sized,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T, U> PartialEq<Exclusive<U>> for Exclusive<T>

where T: Sync + PartialEq<U> + ?Sized, U: Sync + ?Sized,

fn eq(&self, other: &Exclusive<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, U> PartialOrd<Exclusive<U>> for Exclusive<T>

where T: Sync + PartialOrd<U> + ?Sized, U: Sync + ?Sized,

fn partial_cmp(&self, other: &Exclusive<U>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Copy for Exclusive<T>

where T: Sync + Copy,

impl<T> Eq for Exclusive<T>

where T: Sync + Eq + ?Sized,

impl<T> StructuralPartialEq for Exclusive<T>

where T: Sync + StructuralPartialEq + ?Sized,

impl<T: ?Sized> Sync for Exclusive<T>