Exclusive in std::sync - Rust (original) (raw)

pub struct Exclusive<T>

where
    T: ?Sized,

{ /* private fields */ }

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

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

Wrap a value in an Exclusive

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

Unwrap the value contained in the Exclusive

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

Gets exclusive access to the underlying value.

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

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

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

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

The type of value this coroutine yields. Read more

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

The type of value this coroutine returns. Read more

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

Resumes the execution of this coroutine. Read more

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

Performs the call operation.

The returned type after the call operator is used.

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

Performs the call operation.

Converts to this type from the input type.

The type of value produced on completion.

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

Converts to this type from the input type.

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of[From](../convert/trait.From.html "trait std::convert::From")<T> for U chooses to do.

The output that the future will produce on completion.

Which kind of future are we turning this into?

Creates a future from a value. Read more

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

Associated searcher for this pattern

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

Constructs the associated searcher fromself and the haystack to search in.

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

Checks whether the pattern matches anywhere in the haystack

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

Checks whether the pattern matches at the front of the haystack

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

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

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

Checks whether the pattern matches at the back of the haystack

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

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

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

Returns the pattern as utf-8 bytes if possible.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.