Exclusive in core::sync - Rust
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`.

## Exclusive

# Struct Exclusive

Source

    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 `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>

Source

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

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

Wrap a value in an `Exclusive`

Source

#### pub const fn into_inner(self) -> T

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

Unwrap the value contained in the `Exclusive`

Source§

### impl<T: ?Sized> Exclusive<T>

Source

#### 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.

Source

#### 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 `Exclusive`s can produce unpinned access to the underlying value, but pinned `Exclusive`s only produce pinned access to the underlying value.

Source

#### 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`.

Source

#### 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§

Source§

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

Source§

#### fn as_ref(&self) -> &T

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

### impl<T> Clone for Exclusive<T>
where T: Sync + Clone,

Source§

#### fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from `source`. Read more
Source§

### impl<R, G> Coroutine<R> for Exclusive<G>
where G: Coroutine<R> + ?Sized,

Source§

#### 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
Source§

#### 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
Source§

#### 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. Read more
Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

#### fn default() -> Exclusive<T> ⓘ

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

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

Source§

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

🔬This is a nightly-only experimental API. (`fn_traits` #29625)
Performs the call operation.
Source§

### impl<F, Args> FnMut<Args> for Exclusive<F>
where F: FnMut<Args>, Args: Tuple,

Source§

#### 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.
Source§

### impl<F, Args> FnOnce<Args> for Exclusive<F>
where F: FnOnce<Args>, Args: Tuple,

Source§

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

The returned type after the call operator is used.
Source§

#### 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.
Source§

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

Source§

#### fn from(t: T) -> Self

Converts to this type from the input type.
Source§

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

Source§

#### type Output = <T as Future>::Output

The type of value produced on completion.
Source§

#### 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. Read more
Source§

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

Source§

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

Feeds this value into the given `Hasher`. Read more
1.3.0 · Source§

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

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

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

Source§

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

This method returns an `Ordering` between `self` and `other`. Read more
1.21.0 · Source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

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

Restrict a value to a certain interval. Read more
Source§

### impl<T, U> PartialEq<Exclusive<U>> for Exclusive<T>
where T: Sync + PartialEq<U> + ?Sized, U: Sync + ?Sized,

Source§

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

Tests for `self` and `other` values to be equal, and is used by `==`.
1.0.0 · Source§

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

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

### impl<T, U> PartialOrd<Exclusive<U>> for Exclusive<T>
where T: Sync + PartialOrd<U> + ?Sized, U: Sync + ?Sized,

Source§

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

This method returns an ordering between `self` and `other` values if one exists. Read more
1.0.0 · Source§

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

Tests less than (for `self` and `other`) and is used by the `<` operator. Read more
1.0.0 · Source§

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

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

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

Tests greater than (for `self` and `other`) and is used by the `>` operator. Read more
1.0.0 · Source§

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

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

### impl<T> Copy for Exclusive<T>
where T: Sync + Copy,

Source§

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

Source§

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

Source§

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

## 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§

Source§

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

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

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

Mutably borrows from an owned value. Read more
Source§

### impl<T> CloneToUninit for T
where T: Clone,

Source§

#### 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
Source§

### impl<T> From<!> for T

Source§

#### fn from(t: !) -> T

Converts to this type from the input type.
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

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

Source§

### impl<F> IntoFuture for F
where F: Future,

Source§

#### type Output = <F as Future>::Output

The output that the future will produce on completion.
Source§

#### type IntoFuture = F

Which kind of future are we turning this into?
Source§

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

Creates a future from a value. Read more
Source§

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

Source§

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

🔬This is a nightly-only experimental API. (`pattern` #27721)
Associated searcher for this pattern
Source§

#### 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.
Source§

#### 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
Source§

#### 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
Source§

#### 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.
Source§

#### fn is_suffix_of<'a>(self, haystack: &'a str) -> bool
where 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
Source§

#### 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.
Source§

#### 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.
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

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

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.