W3cubDocs

/Rust

Struct Exclusive

pub struct Exclusive<T>where
    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> Exclusive<T>

pub const fn new(t: T) -> Exclusive<T> ⓘ

🔬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> Exclusive<T>where
    T: ?Sized,

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 Exclusive<T>>) -> 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) -> Exclusive<T> ⓘ

Returns a duplicate of the value. Read more

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

Performs copy-assignment from source. Read more

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. Read more

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

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

The type of value this coroutine returns. Read more

fn resume(
    self: Pin<&mut Exclusive<G>>,
    arg: R,
) -> CoroutineState<<Exclusive<G> as Coroutine<R>>::Yield, <Exclusive<G> as Coroutine<R>>::Return>

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

Resumes the execution of this coroutine. Read more

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

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

Formats the value using the given formatter. Read more

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

fn default() -> Exclusive<T> ⓘ

Returns the “default value” for a type. Read more

impl<F, Args> Fn<Args> for Exclusive<F>where
    F: Sync + Fn<Args>,
    Args: Tuple,

extern "rust-call" fn call(
    &self,
    args: Args,
) -> <Exclusive<F> as FnOnce<Args>>::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,
) -> <Exclusive<F> as FnOnce<Args>>::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,
) -> <Exclusive<F> as FnOnce<Args>>::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) -> Exclusive<T> ⓘ

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 Exclusive<T>>,
    cx: &mut Context<'_>,
) -> Poll<<Exclusive<T> as Future>::Output>

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

impl<T> Hash for Exclusive<T>where
    T: Sync + Hash + ?Sized,

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

Feeds this value into the given Hasher. Read more

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

Feeds a slice of this type into the given Hasher. Read more

impl<T> Ord for Exclusive<T>where
    T: Sync + Ord + ?Sized,

fn cmp(&self, other: &Exclusive<T>) -> Ordering

This method returns an Ordering between self and other. Read more

1.21.0Source

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

Compares and returns the maximum of two values. Read more

1.21.0Source

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

Compares and returns the minimum of two values. Read more

1.50.0Source

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

Restrict a value to a certain interval. Read more

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. Read more

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

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

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

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

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

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

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

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

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> Sync for Exclusive<T>where
    T: ?Sized,

Auto Trait Implementations

impl<T> Freeze for Exclusive<T>where
    T: Freeze + ?Sized,

impl<T> RefUnwindSafe for Exclusive<T>where
    T: RefUnwindSafe + ?Sized,

impl<T> Send for Exclusive<T>where
    T: Send + ?Sized,

impl<T> Unpin for Exclusive<T>where
    T: Unpin + ?Sized,

impl<T> UnwindSafe for Exclusive<T>where
    T: UnwindSafe + ?Sized,

Blanket Implementations

impl<T> Any for Twhere
    T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for Twhere
    T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for Twhere
    T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

impl<T> CloneToUninit for Twhere
    T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit #126799)

Performs copy-assignment from self to dest. Read more

impl<T> From<!> for T

fn from(t: !) -> T

Converts to this type from the input type.

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for Twhere
    U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl<F> IntoFuture for Fwhere
    F: Future,

type Output = <F as Future>::Output

The output that the future will produce on completion.

type IntoFuture = F

Which kind of future are we turning this into?

fn into_future(self) -> <F as IntoFuture>::IntoFuture

Creates a future from a value. Read more

impl<F> Pattern for Fwhere
    F: FnMut(char) -> bool,

type Searcher<'a> = CharPredicateSearcher<'a, F>

🔬This is a nightly-only experimental API. (pattern #27721)

Associated searcher for this pattern

fn into_searcher<'a>(self, haystack: &'a str) -> CharPredicateSearcher<'a, F>

🔬This is a nightly-only experimental API. (pattern #27721)

Constructs the associated searcher from self and the haystack to search in.

fn is_contained_in<'a>(self, haystack: &'a str) -> bool

🔬This is a nightly-only experimental API. (pattern #27721)

Checks whether the pattern matches anywhere in the haystack

fn is_prefix_of<'a>(self, haystack: &'a str) -> bool

🔬This is a nightly-only experimental API. (pattern #27721)

Checks whether the pattern matches at the front of the haystack

fn strip_prefix_of<'a>(self, haystack: &'a str) -> Option<&'a str>

🔬This is a nightly-only experimental API. (pattern #27721)

Removes the pattern from the front of haystack, if it matches.

fn is_suffix_of<'a>(self, haystack: &'a str) -> boolwhere
    CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,

🔬This is a nightly-only experimental API. (pattern #27721)

Checks whether the pattern matches at the back of the haystack

fn strip_suffix_of<'a>(self, haystack: &'a str) -> Option<&'a str>where
    CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,

🔬This is a nightly-only experimental API. (pattern #27721)

Removes the pattern from the back of haystack, if it matches.

fn as_utf8_pattern(&self) -> Option<Utf8Pattern<'_>>

🔬This is a nightly-only experimental API. (pattern #27721)

Returns the pattern as utf-8 bytes if possible.

impl<T> ToOwned for Twhere
    T: Clone,

type Owned = T

The resulting type after obtaining ownership.

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T, U> TryFrom<U> for Twhere
    U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.

impl<T, U> TryInto<U> for Twhere
    U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/sync/struct.Exclusive.html