Struct SyncView 

pub struct SyncView<T>
where
    T: ?Sized,
{ /* private fields */ }

SyncView 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 SyncView to unconditionally implement Sync. Indeed, the safety requirements of Sync state that for SyncView to be Sync, it must be sound to share across threads, that is, it must be sound for &SyncView to cross thread boundaries. By design, a &SyncView<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 SyncView can be used as hint to the Rust compiler that something is Sync in practice.

Examples

A non-Sync field prevents the wrapping struct from being Sync:

use std::sync::mpsc::{self, Receiver};

struct Inbox {
    name: &'static str,
    receiver: Receiver<u32>,
}

fn require_send<T: Send>() {}
fn require_send_sync<T: Send + Sync>() {}

require_send::<Inbox>();      // compiled
require_send_sync::<Inbox>(); // compile-failed

SyncView makes the value Sync without stripping the struct of its functionality:

use std::sync::SyncView;
use std::sync::mpsc::{self, Receiver};
use std::thread;

struct Inbox {
    name: &'static str,
    receiver: SyncView<Receiver<u32>>,
}

impl Inbox {
    fn name(&self) -> &'static str {
        self.name
    }

    fn recv(&mut self) -> u32 {
        self.receiver.as_mut().recv().unwrap()
    }
}

let (sender, receiver) = mpsc::channel();
let mut inbox = Inbox { name: "jobs", receiver: SyncView::new(receiver) };
sender.send(42).unwrap();
drop(sender);

thread::scope(|scope| {
    let reader = scope.spawn(|| inbox.name());
    assert_eq!(inbox.name(), "jobs");
    assert_eq!(reader.join().unwrap(), "jobs");
});

let message = thread::spawn(move || inbox.recv()).join().unwrap();
assert_eq!(message, 42);
println!("Shared Inbox across threads, then moved it to a worker and received 42");

Parallels with a mutex

In some sense, SyncView 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> SyncView<T>

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

Wrap a value in an SyncView

pub const fn into_inner(self) -> T

Unwrap the value contained in the SyncView

impl<T> SyncView<T>

where T: ?Sized,

pub const fn as_pin_mut(self: Pin<&mut SyncView<T>>) -> Pin<&mut T>

Gets pinned exclusive access to the underlying value.

SyncView is considered to structurally pin the underlying value, which means unpinned SyncViews can produce unpinned access to the underlying value, but pinned SyncViews only produce pinned access to the underlying value.

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

Build a mutable reference to an SyncView<T> from a mutable reference to a T. This allows you to skip building an SyncView with SyncView::new.

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

Build a pinned mutable reference to an SyncView<T> from a pinned mutable reference to a T. This allows you to skip building an SyncView with SyncView::new.

impl<T> SyncView<T>

where T: Sync + ?Sized,

pub const fn as_pin_ref(self: Pin<&SyncView<T>>) -> Pin<&T>

Gets pinned shared access to the underlying value.

SyncView is considered to structurally pin the underlying value, which means unpinned SyncViews can produce unpinned access to the underlying value, but pinned SyncViews only produce pinned access to the underlying value.

Trait Implementations

impl<T> AsMut<T> for SyncView<T>

where T: ?Sized,

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

Gets exclusive access to the underlying value.

impl<T> AsRef<T> for SyncView<T>

where T: Sync + ?Sized,

fn as_ref(&self) -> &T

Gets shared access to the underlying value.

impl<F, Args> AsyncFn<Args> for SyncView<F>

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

extern "rust-call" fn async_call( &self, args: Args, ) -> <SyncView<F> as AsyncFnMut<Args>>::CallRefFuture<'_>

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

Call the AsyncFn, returning a future which may borrow from the called closure.

impl<F, Args> AsyncFnMut<Args> for SyncView<F>

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

type CallRefFuture<'a> = <F as AsyncFnMut<Args>>::CallRefFuture<'a> where F: 'a

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

Future returned by AsyncFnMut::async_call_mut and AsyncFn::async_call.

extern "rust-call" fn async_call_mut( &mut self, args: Args, ) -> <SyncView<F> as AsyncFnMut<Args>>::CallRefFuture<'_>

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

Call the AsyncFnMut, returning a future which may borrow from the called closure.

impl<F, Args> AsyncFnOnce<Args> for SyncView<F>

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

type CallOnceFuture = <F as AsyncFnOnce<Args>>::CallOnceFuture

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

Future returned by AsyncFnOnce::async_call_once.

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

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

Output type of the called closure’s future.

extern "rust-call" fn async_call_once( self, args: Args, ) -> <SyncView<F> as AsyncFnOnce<Args>>::CallOnceFuture

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

Call the AsyncFnOnce, returning a future which may move out of the called closure.

impl<T> Clone for SyncView<T>

where T: Sync + Clone,

fn clone(&self) -> SyncView<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Copy for SyncView<T>

where T: Sync + Copy,

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

where G: Coroutine<R> + ?Sized,

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

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

The type of value this coroutine yields.

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

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

The type of value this coroutine returns.

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

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

Resumes the execution of this coroutine.

impl<T> Debug for SyncView<T>

where T: ?Sized,

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

Formats the value using the given formatter.

impl<T> Default for SyncView<T>

where T: Default,

fn default() -> SyncView<T>

Returns the “default value” for a type.

impl<T> Eq for SyncView<T>

where T: Sync + Eq + ?Sized,

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

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

extern "rust-call" fn call( &self, args: Args, ) -> <SyncView<F> as FnOnce<Args>>::Output

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

Performs the call operation.

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

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

extern "rust-call" fn call_mut( &mut self, args: Args, ) -> <SyncView<F> as FnOnce<Args>>::Output

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

Performs the call operation.

impl<F, Args> FnOnce<Args> for SyncView<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, ) -> <SyncView<F> as FnOnce<Args>>::Output

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

Performs the call operation.

impl<T> From<T> for SyncView<T>

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

Converts to this type from the input type.

impl<T> Future for SyncView<T>

where T: Future + ?Sized,

type Output = <T as Future>::Output

The type of value produced on completion.

fn poll( self: Pin<&mut SyncView<T>>, cx: &mut Context<'_>, ) -> Poll<<SyncView<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.

impl<T> Hash for SyncView<T>

where T: Sync + Hash + ?Sized,

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

where H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for SyncView<T>

where T: Sync + Ord + ?Sized,

fn cmp(&self, other: &SyncView<T>) -> 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.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

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

Restrict a value to a certain range.

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

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

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

Equality operator ==.

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

Inequality operator !=.

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

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

fn partial_cmp(&self, other: &SyncView<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> StructuralPartialEq for SyncView<T>

where T: Sync + StructuralPartialEq + ?Sized,

impl<T> Sync for SyncView<T>

where T: ?Sized,