Struct moxie::Key

pub struct Key<State> { /* fields omitted */ }

A Key offers access to a state variable. The key allows reads of the state variable through a snapshot taken when the Key was created. Writes are supported with Key::update and Key::set.

They are created with the cache_state and state functions.

See state and cache_state for examples.

Implementations

impl<State> Key<State>

pub fn id(&self) -> CallId

Returns the topo::CallId at which the state variable is bound.

pub fn update(&self, updater: impl FnOnce(&State) -> Option<State>)

Runs updater with a reference to the state variable’s latest value, and enqueues a commit to the variable if updater returns Some. Returns the Revision at which the state variable was last rooted if the variable is live, otherwise returns None.

Enqueuing the commit invokes the state change waker registered with the Runtime (if any) to ensure that the code embedding the runtime schedules another call of run_once.

This should be called during event handlers or other code which executes outside of a Revision’s execution, otherwise unpredictable waker behavior may be obtained.

Example

use futures::task::waker;
use moxie::{runtime::RunLoop, state, testing::BoolWaker};

// this runtime holds a single state variable
let mut rt = RunLoop::new(|| state(|| 0u64));

let track_wakes = BoolWaker::new();
rt.set_state_change_waker(waker(track_wakes.clone()));

let (first_commit, first_key) = rt.run_once();
assert_eq!(*first_commit, 0, "no updates yet");
assert!(!track_wakes.is_woken(), "no updates yet");

first_key.update(|_| None); // this is a no-op
assert_eq!(*first_key, 0, "no updates yet");
assert!(!track_wakes.is_woken(), "no updates yet");

first_key.update(|prev| Some(prev + 1));
assert_eq!(*first_key, 0, "update only enqueued, not yet committed");
assert!(track_wakes.is_woken());

let (second_commit, second_key) = rt.run_once(); // this commits the pending update
assert_eq!(*second_key, 1);
assert_eq!(*second_commit, 1);
assert_eq!(*first_commit, 0, "previous value still held by previous pointer");
assert!(!track_wakes.is_woken(), "wakes only come from updating state vars");
assert_eq!(first_key, second_key, "same state variable");

impl<State> Key<State> where
    State: PartialEq, 

pub fn set(&self, new: State)

Commits a new state value if it is unequal to the current value and the state variable is still live. Has the same properties as update regarding waking the runtime.

See state and cache_state for examples.

impl<State> Key<State> where
    State: Clone + PartialEq, 

pub fn mutate(&self, op: impl FnOnce(&mut State))

Mutates a copy of the current state, committing the update if it results in a change. Has the same properties as update See state and cache_state for examples.

Trait Implementations

impl<State> Clone for Key<State>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<State> Debug for Key<State> where
    State: Debug, 

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

Formats the value using the given formatter.

impl<State> Deref for Key<State>

type Target = State

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<State> Display for Key<State> where
    State: Display, 

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

Formats the value using the given formatter.

impl<State> Hash for Key<State>

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<State> PartialEq<Key<State>> for Key<State>

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

Keys are considered equal if they point to the same state variable. Importantly, they will compare as equal even if they contain different snapshots of the state variable due to having been initialized in different revisions.

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

This method tests for !=.

impl<State> Eq for Key<State>