pub struct Exclusive<T>where
    T: ?Sized,{ /* private fields */ }
🔬This is a nightly-only experimental API. (exclusive_wrapper)
Available on non-crate feature miri-test-libstd only.
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 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 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§

source§

impl<T> Exclusive<T>

source

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

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

Wrap a value in an Exclusive

source

pub const fn into_inner(self) -> T

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

Unwrap the value contained in the Exclusive

source§

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

source

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

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

Get exclusive access to the underlying value.

source

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

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

Get 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

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

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

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)

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

source§

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

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

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

source§

fn default() -> Exclusive<T>

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

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

source§

fn from(t: T) -> Exclusive<T>

Converts to this type from the input type.
source§

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

§

type Output = <T as Future>::Output

The type of value produced on completion.
source§

fn poll( self: Pin<&mut Exclusive<T>>, cx: &mut Context<'_> ) -> Poll<<Exclusive<T> as Future>::Output>

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

Auto Trait Implementations§

§

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

§

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

§

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

§

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

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere T: 'a,

§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

§

impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere T: 'a,

§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self, E>

source§

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

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

const: unstable · source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<!> for T

const: unstable · source§

fn from(t: !) -> T

Converts to this type from the input type.
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FutureExt for Twhere T: Future + ?Sized,

§

fn map<U, F>(self, f: F) -> Map<Self, F> where F: FnOnce(Self::Output) -> U, Self: Sized,

Map this future’s output to a different type, returning a new future of the resulting type. Read more
§

fn map_into<U>(self) -> MapInto<Self, U> where Self::Output: Into<U>, Self: Sized,

Map this future’s output to a different type, returning a new future of the resulting type. Read more
§

fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> where F: FnOnce(Self::Output) -> Fut, Fut: Future, Self: Sized,

Chain on a computation for when a future finished, passing the result of the future to the provided closure f. Read more
§

fn left_future<B>(self) -> Either<Self, B> where B: Future<Output = Self::Output>, Self: Sized,

Wrap this future in an Either future, making it the left-hand variant of that Either. Read more
§

fn right_future<A>(self) -> Either<A, Self> where A: Future<Output = Self::Output>, Self: Sized,

Wrap this future in an Either future, making it the right-hand variant of that Either. Read more
§

fn into_stream(self) -> IntoStream<Self>where Self: Sized,

Convert this future into a single element stream. Read more
§

fn flatten(self) -> Flatten<Self> where Self::Output: Future, Self: Sized,

Flatten the execution of this future when the output of this future is itself another future. Read more
§

fn flatten_stream(self) -> FlattenStream<Self>where Self::Output: Stream, Self: Sized,

Flatten the execution of this future when the successful result of this future is a stream. Read more
§

fn fuse(self) -> Fuse<Self> where Self: Sized,

Fuse a future such that poll will never again be called once it has completed. This method can be used to turn any Future into a FusedFuture. Read more
§

fn inspect<F>(self, f: F) -> Inspect<Self, F> where F: FnOnce(&Self::Output), Self: Sized,

Do something with the output of a future before passing it on. Read more
§

fn catch_unwind(self) -> CatchUnwind<Self> where Self: Sized + UnwindSafe,

Available on crate feature std only.
Catches unwinding panics while polling the future. Read more
§

fn shared(self) -> Shared<Self> where Self: Sized, Self::Output: Clone,

Available on crate feature std only.
Create a cloneable handle to this future where all handles will resolve to the same result. Read more
§

fn remote_handle(self) -> (Remote<Self>, RemoteHandle<Self::Output>)where Self: Sized,

Available on crate features channel and std only.
Turn this future into a future that yields () on completion and sends its output to another future on a separate task. Read more
§

fn boxed<'a>( self ) -> Pin<Box<dyn Future<Output = Self::Output> + Send + 'a, Global>>where Self: Sized + Send + 'a,

Available on crate feature alloc only.
Wrap the future in a Box, pinning it. Read more
§

fn boxed_local<'a>( self ) -> Pin<Box<dyn Future<Output = Self::Output> + 'a, Global>>where Self: Sized + 'a,

Available on crate feature alloc only.
Wrap the future in a Box, pinning it. Read more
§

fn unit_error(self) -> UnitError<Self> where Self: Sized,

§

fn never_error(self) -> NeverError<Self> where Self: Sized,

§

fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>where Self: Unpin,

A convenience for calling Future::poll on Unpin future types.
§

fn now_or_never(self) -> Option<Self::Output>where Self: Sized,

Evaluates and consumes the future, returning the resulting output if the future is ready after the first call to Future::poll. Read more
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

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

const: unstable · 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 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?
source§

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

Creates a future from a value. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = mem::align_of::<T>()

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

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

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

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

Performs the conversion.
§

impl<F, T, E> TryFuture for Fwhere F: Future<Output = Result<T, E>> + ?Sized,

§

type Ok = T

The type of successful values yielded by this future
§

type Error = E

The type of failures yielded by this future
§

fn try_poll( self: Pin<&mut F>, cx: &mut Context<'_> ) -> Poll<<F as Future>::Output>

Poll this TryFuture as if it were a Future. Read more
§

impl<Fut> TryFutureExt for Futwhere Fut: TryFuture + ?Sized,

§

fn flatten_sink<Item>(self) -> FlattenSink<Self, Self::Ok>where Self::Ok: Sink<Item, Error = Self::Error>, Self: Sized,

Available on crate feature sink only.
Flattens the execution of this future when the successful result of this future is a Sink. Read more
§

fn map_ok<T, F>(self, f: F) -> MapOk<Self, F> where F: FnOnce(Self::Ok) -> T, Self: Sized,

Maps this future’s success value to a different value. Read more
§

fn map_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E> where F: FnOnce(Self::Ok) -> T, E: FnOnce(Self::Error) -> T, Self: Sized,

Maps this future’s success value to a different value, and permits for error handling resulting in the same type. Read more
§

fn map_err<E, F>(self, f: F) -> MapErr<Self, F> where F: FnOnce(Self::Error) -> E, Self: Sized,

Maps this future’s error value to a different value. Read more
§

fn err_into<E>(self) -> ErrInto<Self, E> where Self: Sized, Self::Error: Into<E>,

Maps this future’s Error to a new error type using the Into trait. Read more
§

fn ok_into<U>(self) -> OkInto<Self, U> where Self: Sized, Self::Ok: Into<U>,

Maps this future’s Ok to a new type using the Into trait.
§

fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> where F: FnOnce(Self::Ok) -> Fut, Fut: TryFuture<Error = Self::Error>, Self: Sized,

Executes another future after this one resolves successfully. The success value is passed to a closure to create this subsequent future. Read more
§

fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> where F: FnOnce(Self::Error) -> Fut, Fut: TryFuture<Ok = Self::Ok>, Self: Sized,

Executes another future if this one resolves to an error. The error value is passed to a closure to create this subsequent future. Read more
§

fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F> where F: FnOnce(&Self::Ok), Self: Sized,

Do something with the success value of a future before passing it on. Read more
§

fn inspect_err<F>(self, f: F) -> InspectErr<Self, F> where F: FnOnce(&Self::Error), Self: Sized,

Do something with the error value of a future before passing it on. Read more
§

fn try_flatten(self) -> TryFlatten<Self, Self::Ok> where Self::Ok: TryFuture<Error = Self::Error>, Self: Sized,

Flatten the execution of this future when the successful result of this future is another future. Read more
§

fn try_flatten_stream(self) -> TryFlattenStream<Self>where Self::Ok: TryStream<Error = Self::Error>, Self: Sized,

Flatten the execution of this future when the successful result of this future is a stream. Read more
§

fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> where Self: Sized, F: FnOnce(Self::Error) -> Self::Ok,

Unwraps this future’s output, producing a future with this future’s Ok type as its Output type. Read more
§

fn into_future(self) -> IntoFuture<Self> where Self: Sized,

Wraps a [TryFuture] into a type that implements Future. Read more
§

fn try_poll_unpin( &mut self, cx: &mut Context<'_> ) -> Poll<Result<Self::Ok, Self::Error>>where Self: Unpin,

A convenience method for calling [TryFuture::try_poll] on Unpin future types.
source§

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.
const: unstable · source§

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

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more