Struct SendRc

pub struct SendRc<T> { /* private fields */ }

Reference-counting pointer like Rc<T>, but which is Send if T is Send.

When created, a SendRc is pinned to the current thread, and is usable only within it. Before sending it to a different thread, you must use SendRc::pre_send() to park all the SendRcs that point to the same value. This will make the values temporarily inaccessible through SendRcs, but will allow safe transfer. When done parking, you can obtain a PostSend and send it to the other thread to restore access to the values there. For example:

// create two SendRcs pointing to a shared value
let mut r1 = SendRc::new(RefCell::new(1));
let mut r2 = SendRc::clone(&r1);

// prepare to send them to a different thread
let pre_send = SendRc::pre_send();
pre_send.park(&mut r1); // r1 and r2 cannot be dereferenced from this point
pre_send.park(&mut r2);
// ready() would panic if there were unparked SendRcs pointing to the value
let post_send = pre_send.ready();

// move everything to a different thread
std::thread::spawn(move || {
    // SendRcs are still unusable until unparked
    post_send.unpark();
    // they're again usable from this point, and only in this thread
    *r1.borrow_mut() += 1;
    assert_eq!(*r2.borrow(), 2);
})

This process may be repeated to send the SendRcs to another thread later.

Compared to Rc, tradeoffs of a SendRc are:

• deref(), clone(), and drop() require a check that the shared value is not parked, and a check that we’re accessing it from the correct thread.
• a SendRc takes up two machine words.
• it currently doesn’t support weak pointers.

Implementations

impl<T> SendRc<T>

pub fn new(val: T) -> Self

Constructs a new SendRc<T>.

The SendRc is only usable from the current thread. To send and use it in another thread, you must call pre_send().

pub fn pre_send() -> PreSend<T>

Prepare to send SendRcs to another thread.

To move a SendRc to a different thread, you must call park() on that pointer, as well as on all other SendRcs pointing to the same value.

let mut r1 = SendRc::new(RefCell::new(1));
let mut r2 = SendRc::clone(&r1);
let pre_send = SendRc::pre_send();
pre_send.park(&mut r1);
pre_send.park(&mut r2);
let post_send = pre_send.ready();
// post_send, r1, and r2 can now be send to a different thread, and re-enabled
// by calling post_send.unpark()

pub fn strong_count(this: &Self) -> usize

Returns the number of SendRcs pointing to the value.

Panics when invoked from a different thread than the one the SendRc was created in or last pinned to.

pub fn try_unwrap(this: Self) -> Result<T, Self>

Returns the value if the SendRc has exactly one reference.

Panics when invoked from a different thread than the one the SendRc was created in or last pinned to.

pub fn get_mut(this: &mut Self) -> Option<&mut T>

Returns a mutable reference to the value this points to, if no other SendRcs point to the same value.

Panics when invoked from a different thread than the one the SendRc was created in or last pinned to.

pub fn ptr_eq(this: &Self, other: &Self) -> bool

Returns true if this and other point to the same value.

This method can be called from any thread.

Trait Implementations

impl<T> AsRef<T> for SendRc<T>

fn as_ref(&self) -> &T

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

impl<T> Borrow<T> for SendRc<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T> Clone for SendRc<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for SendRc<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for SendRc<T>

fn default() -> SendRc<T>

Returns the “default value” for a type.

impl<T> Deref for SendRc<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: Display> Display for SendRc<T>

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

Formats the value using the given formatter.

impl<T> Drop for SendRc<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Hash> Hash for SendRc<T>

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

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> Ord for SendRc<T>

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

impl<T: PartialEq> PartialEq for SendRc<T>

fn eq(&self, other: &SendRc<T>) -> 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: PartialOrd> PartialOrd for SendRc<T>

fn partial_cmp(&self, other: &SendRc<T>) -> 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: Eq> Eq for SendRc<T>

impl<T> Send for SendRc<T>

where T: Send,