Struct wnf::BorrowedState

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

A borrowed state

This has a lifetime parameter to tie it to something that owns the state, typically an OwnedState<T>.

Unlike OwnedState<T>, this implements Copy (and Clone) and does not delete the represented state on drop.

While borrowing in Rust usually refers to borrowing memory, this applies the idea of borrowing to an external entity, namely a state. It’s similar to BorrowedHandle<'_> in that regard.

Calling Clone::clone on a BorrowedState<'a, T> just makes a trivial copy, returning another BorrowedState<'a, T> with the same lifetime as the original one and representing the same underlying WNF state. The same applies to the ToOwned::to_owned method. If you want to turn a BorrowedState<'_, T> into an OwnedState<T> (which will then delete the underlying state on drop), use the BorrowedState::to_owned_state method.

The type parameter T is the type of data contained in the state.

Implementations

impl<T> BorrowedState<'_, T>where
    T: Read<T> + NoUninit,

pub fn apply<D, F>(self, transform: F) -> Result<D>where
    D: Borrow<T>,
    F: FnMut(T) -> D,

Applies a transformation to the data of this state

See OwnedState::apply

pub fn try_apply<D, E, F>(self, transform: F) -> Result<D>where
    D: Borrow<T>,
    E: Into<Box<dyn Error + Send + Sync>>,
    F: FnMut(T) -> Result<D, E>,

Applies a fallible transformation to the data of this state

See OwnedState::try_apply

impl<T> BorrowedState<'_, T>where
    T: Read<Box<T>> + NoUninit + ?Sized,

pub fn apply_boxed<D, F>(self, transform: F) -> Result<D>where
    D: Borrow<T>,
    F: FnMut(Box<T>) -> D,

Applies a transformation to the data of this state as a box

See OwnedState::apply_boxed

pub fn try_apply_boxed<D, E, F>(self, transform: F) -> Result<D>where
    D: Borrow<T>,
    E: Into<Box<dyn Error + Send + Sync>>,
    F: FnMut(Box<T>) -> Result<D, E>,

Applies a fallible transformation to the data of this state as a box

See OwnedState::try_apply_boxed

impl<T> BorrowedState<'_, T>where
    T: ?Sized,

pub fn exists(self) -> Result<bool>

Returns whether this state exists

See OwnedState::exists

pub fn subscribers_present(self) -> Result<bool>

Returns whether this state has at least one subscriber

See OwnedState::subscribers_present

pub fn is_quiescent(self) -> Result<bool>

Returns whether this state is “quiescent”, i.e. none of the listeners subscribed to it are currently running

See OwnedState::is_quiescent

impl<T> BorrowedState<'static, T>where
    T: ?Sized,

pub fn create_temporary() -> Result<Self>

Creates a BorrowedState<'static, T> with temporary lifetime and machine scope

This is a convenience method for quickly creating a state, e.g. for testing purposes. For more precise control over the created state, use the StateCreation builder.

Note that a newly created state is initialized with data of size zero. This means that unless the data type T is zero-sized or a slice type, you need to update the state data with a value of type T before querying it for the first time.

Errors

Returns an error if creating the state fails

impl<T> BorrowedState<'_, T>where
    T: ?Sized,

pub fn delete(self) -> Result<()>

Deletes this state

Returns an error if deleting the state fails

impl<T> BorrowedState<'_, T>where
    T: Read<T>,

pub fn get(self) -> Result<T>

Queries the data of this state

See OwnedState::get

pub fn query(self) -> Result<StampedData<T>>

Queries the data of this state together with its change stamp

See OwnedState::query

impl<T> BorrowedState<'_, T>where
    T: Read<Box<T>> + ?Sized,

pub fn get_boxed(self) -> Result<Box<T>>

Queries the data of this state as a box

See OwnedState::get_boxed

pub fn query_boxed(self) -> Result<StampedData<Box<T>>>

Queries the data of this state as a box together with its change stamp

See OwnedState::query_boxed

impl<T> BorrowedState<'_, T>where
    T: ?Sized,

pub fn change_stamp(self) -> Result<ChangeStamp>

Queries the change stamp of this state

See OwnedState::change_stamp

impl<T> BorrowedState<'_, T>where
    T: Read<T> + NoUninit,

pub fn replace(self, new_value: &T) -> Result<T>

Replaces the data of this state, returning the previous value

See OwnedState::replace

impl<T> BorrowedState<'_, T>where
    T: Read<Box<T>> + NoUninit + ?Sized,

pub fn replace_boxed(self, new_value: &T) -> Result<Box<T>>

Replaces the data of this state, returning the previous value as a box

See OwnedState::replace_boxed

impl<'a, T> BorrowedState<'a, T>where
    T: ?Sized,

pub const fn state_name(self) -> StateName

Returns the name of this state

pub const fn to_owned_state(self) -> OwnedState<T>

Turns this BorrowedState<'_, T> into an OwnedState<T> representing the same underlying state

Note that the underlying state will be deleted when the OwnedState<T> is dropped.

pub const fn cast<U>(self) -> BorrowedState<'a, U>where
    U: ?Sized,

Casts the data type of this state to a different type U

The returned BorrowedState<'a, U> represents the same underlying state, but treats it as containing data of a different type U.

impl<T> BorrowedState<'static, T>where
    T: ?Sized,

pub fn from_state_name(state_name: impl Into<StateName>) -> Self

Statically borrows the state with the given name

Note that an underlying state with the given name may or may not exist. The returned BorrowedState<'static, T> having a 'static lifetime just means that the state is borrowed directly from the system rather than from an OwnedState<T> that will be dropped at some point.

pub fn from_state_name_and_type_id(
    state_name: impl Into<StateName>,
    type_id: impl Into<GUID>
) -> Self

Statically borrows the state with the given name using the given type id

Note that an underlying state with the given name may or may not exist. The returned BorrowedState<'static, T> having a 'static lifetime just means that the state is borrowed directly from the system rather than from an OwnedState<T> that will be dropped at some point.

impl<T> BorrowedState<'_, T>where
    T: NoUninit + ?Sized,

pub fn set(self, data: &T) -> Result<()>

Updates the data of this state with the given value

See OwnedState::set

pub fn update(
    self,
    data: &T,
    expected_change_stamp: impl Into<ChangeStamp>
) -> Result<bool>

Updates the data of this state with the given value

See OwnedState::update

impl<'a, T> BorrowedState<'a, T>where
    T: ?Sized,

pub fn subscribe<F>(
    self,
    listener: F,
    last_seen_change_stamp: SeenChangeStamp
) -> Result<Subscription<'a, F>>where
    F: StateListener<T> + Send + 'static,

Available on crate feature subscribe only.

Subscribes the given state listener to this state

See OwnedState::subscribe

impl<'a, T> BorrowedState<'a, T>where
    T: ?Sized,

pub fn wait_async(self) -> Wait<'a>

Available on crate feature wait_async only.

Waits until this state is updated

See OwnedState::wait_async

impl<'a, T> BorrowedState<'a, T>where
    T: Read<T>,

pub fn wait_until_async<F>(self, predicate: F) -> WaitUntil<'a, T, F> where
    F: FnMut(&T) -> bool,

Available on crate feature wait_async only.

Waits until the data of this state satisfy a given predicate, returning the data

See OwnedState::wait_until_async

impl<'a, T> BorrowedState<'a, T>where
    T: Read<Box<T>> + ?Sized,

pub fn wait_until_boxed_async<F>(self, predicate: F) -> WaitUntilBoxed<'a, T, F> where
    F: FnMut(&T) -> bool,

Available on crate feature wait_async only.

Waits until the data of this state satisfy a given predicate, returning the data as a box

See OwnedState::wait_until_boxed_async

impl<T> BorrowedState<'_, T>where
    T: ?Sized,

pub fn wait_blocking(self, timeout: Duration) -> Result<()>

Available on crate feature wait_blocking only.

Waits until this state is updated

See OwnedState::wait_blocking

impl<T> BorrowedState<'_, T>where
    T: Read<T>,

pub fn wait_until_blocking<F>(self, predicate: F, timeout: Duration) -> Result<T>where
    F: FnMut(&T) -> bool,

Available on crate feature wait_blocking only.

Waits until the data of this state satisfy a given predicate, returning the data

See OwnedState::wait_until_blocking

impl<T> BorrowedState<'_, T>where
    T: Read<Box<T>> + ?Sized,

pub fn wait_until_boxed_blocking<F>(
    self,
    predicate: F,
    timeout: Duration
) -> Result<Box<T>>where
    F: FnMut(&T) -> bool,

Available on crate feature wait_blocking only.

Waits until the data of this state satisfy a given predicate, returning the data as a box

See OwnedState::wait_until_boxed_blocking

Trait Implementations

impl<T> AsState for BorrowedState<'_, T>where
    T: ?Sized,

type Data = T

The type of the data contained in the borrowed state

fn as_state(&self) -> BorrowedState<'_, T>

Borrows a value as a state

impl<T> Clone for BorrowedState<'_, T>where
    T: ?Sized,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for BorrowedState<'_, T>where
    T: ?Sized,

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

Formats the value using the given formatter.

impl<T> Hash for BorrowedState<'_, T>where
    T: ?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> PartialEq<BorrowedState<'_, T>> for BorrowedState<'_, T>where
    T: ?Sized,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Copy for BorrowedState<'_, T>where
    T: ?Sized,

impl<T> Eq for BorrowedState<'_, T>where
    T: ?Sized,