Struct Sticky 

pub struct Sticky<T: 'static> { /* private fields */ }

A Sticky<T> keeps a value T stored in a thread.

This type works similar in nature to Fragile and exposes a similar interface. The difference is that whereas Fragile has its destructor called in the thread where the value was sent, a Sticky that is moved to another thread will have the internal destructor called when the originating thread tears down.

Because Sticky allows values to be kept alive for longer than the Sticky itself, it requires all its contents to be 'static for soundness. Access to the value is limited to scoped callbacks so references cannot outlive the callback or the originating thread.

As this uses TLS internally the general rules about the platform limitations of destructors for TLS apply.

A Sticky<T> is Unpin only if T is Unpin. This ensures that once a wrapped value has been pinned through the Future or Stream implementation, it cannot later be moved out of the wrapper.

Implementations

impl<T> Sticky<T>

pub fn new(value: T) -> Self

Creates a new Sticky wrapping a value.

The value that is moved into the Sticky can be non Send and will be anchored to the thread that created the object. If the sticky wrapper type ends up being send from thread to thread only the original thread can interact with the value.

pub fn is_valid(&self) -> bool

Returns true if the access is valid.

This will be false if the value was sent to another thread. It is also false once its originating registry starts being destroyed, even on platforms that subsequently reinitialize thread local storage.

pub fn into_inner(self) -> T

Consumes the Sticky, returning the wrapped value.

Panics

Panics if called from a different thread than the one where the original value was created, or if that thread is already destroying its thread local storage.

pub fn try_into_inner(self) -> Result<T, Self>

Consumes the Sticky, returning the wrapped value if successful.

The wrapped value is returned if this is called from the same thread as the one where the original value was created, otherwise the Sticky is returned as Err(self).

pub fn with<R, F>(&self, f: F) -> R

where F: for<'a> FnOnce(&'a T) -> R,

Invokes a callback with a shared reference to the wrapped value.

The callback may return owned data, but it cannot return a reference derived from the wrapped value. This keeps every borrow within the lifetime of the originating thread.

use fragile::Sticky;

let value = Sticky::new(String::from("hello"));
let length = value.with(String::len);
assert_eq!(length, 5);

A future borrowing the value cannot escape the callback. Clone or otherwise create owned data before returning a future:

use fragile::Sticky;

let value = Sticky::new(String::from("hello"));
let future = value.with(|value| {
    let value = value.clone();
    async move {
        std::future::ready(()).await;
        assert_eq!(value, "hello");
    }
});

Panics

Panics if the calling thread is not the one that wrapped the value, or if that thread is already destroying its thread local storage. For a non-panicking variant, use try_with.

pub fn with_mut<R, F>(&mut self, f: F) -> R

where F: for<'a> FnOnce(&'a mut T) -> R,

Invokes a callback with an exclusive reference to the wrapped value.

The callback may return owned data, but it cannot return a reference derived from the wrapped value.

use fragile::Sticky;

let mut value = Sticky::new(String::from("hello"));
value.with_mut(|value| value.push_str(" world"));
assert_eq!(value.with(Clone::clone), "hello world");

Panics

Panics if the calling thread is not the one that wrapped the value, or if that thread is already destroying its thread local storage. For a non-panicking variant, use try_with_mut.

pub fn try_with<R, F>(&self, f: F) -> Result<R, InvalidThreadAccess>

where F: for<'a> FnOnce(&'a T) -> R,

Invokes a callback with a shared reference to the wrapped value.

As with with, the callback cannot return a reference derived from the wrapped value.

Returns InvalidThreadAccess without invoking the callback if is_valid is false, that is when called from a thread other than the one that wrapped the value or while that thread is destroying its thread local storage.

pub fn try_with_mut<R, F>(&mut self, f: F) -> Result<R, InvalidThreadAccess>

where F: for<'a> FnOnce(&'a mut T) -> R,

Invokes a callback with an exclusive reference to the wrapped value.

As with with_mut, the callback cannot return a reference derived from the wrapped value.

Returns InvalidThreadAccess without invoking the callback if is_valid is false, that is when called from a thread other than the one that wrapped the value or while that thread is destroying its thread local storage.

Trait Implementations

impl<T: Clone> Clone for Sticky<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Sticky<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for Sticky<T>

fn default() -> Sticky<T>

Returns the “default value” for a type.

impl<T: Display> Display for Sticky<T>

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

Formats the value using the given formatter.

impl<T> Drop for Sticky<T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: Eq> Eq for Sticky<T>

impl<T> From<T> for Sticky<T>

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

Converts to this type from the input type.

impl<F: Future> Future for Sticky<F>

type Output = <F as Future>::Output

The type of value produced on completion.

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.

impl<T: Ord> Ord for Sticky<T>

fn cmp(&self, other: &Sticky<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: PartialEq> PartialEq for Sticky<T>

fn eq(&self, other: &Sticky<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: PartialOrd> PartialOrd for Sticky<T>

fn partial_cmp(&self, other: &Sticky<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Sticky<T>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Sticky<T>) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Sticky<T>) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Sticky<T>) -> bool

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

impl<T> Send for Sticky<T>

impl<S: Stream> Stream for Sticky<S>

type Item = <S as Stream>::Item

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<T> Sync for Sticky<T>

impl<T: Unpin> Unpin for Sticky<T>