Crate moxie[−][src]
Expand description
moxie aims to empower everyone to build reliable and efficient human interfaces.
moxie supports incremental “declarative” Rust code for interactive systems. It comes with a lightweight event loop runtime that supports granular reuse of arbitrary work, state change notifications, and async loaders.
Most users of this crate will do so through a “moxie embedding” like
moxie-dom which is responsible for integrating moxie with a broader
environment. The functions in this module are applicable to any moxie
embedding but end users should not expect to set up their own embedding (see
the runtime module for information on embeddings).
Revisions
The runtime::Revision is a core concept for a moxie
runtime::Runtime: it’s the notion of time passing. In typical
embeddings, every frame results in a new revision.
Topologically nested functions
The functions in this module are intended to be called repeatedly, possibly
on every revision. The results returned must be stable across revisions,
so we use the topo crate to provide stable cache keys for each invocation.
Each function in the root module is annotated with #[topo::nested] and
will inherit the topo::CallId within which it’s called.
Caching
Nearly all UIs benefit from reusing results between frames, in moxie this is
supported by the cache, cache_with, once, and once_with
functions. Values returned from cached closures are available in subsequent
runtime::Revisions at the same callsite and are dropped from the cache
at the end of the first revision where they were not used.
State
State variables are stored in the cache and can be mutated in between
revisions. They are declared with the cache_state and state
functions which return a Commit for reading the current value and a
Key for updating it. Updates to state variables wake the runtime,
initiating a new revision.
Loading Futures
Futures can be “loaded” by the runtime using the load, load_with,
load_once, and load_once_with functions. These functions ensure the
future is spawned to an async executor and return its status on every
revision. When the future has completed, Poll::Ready is returned on
each revision. If a revision occurs without referencing the pending future,
the task is cancelled.
Modules
Utilities for testing moxie-based programs.
Structs
A read-only pointer to the value of a state variable at a particular revision.
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.
Functions
Memoizes init at this callsite, cloning a cached Output if it exists and
Input is the same as when the stored value was created.
Root a state variable at this callsite, returning a Key to the state
variable. Re-initializes the state variable if the capture arg changes.
Cache the return of the init function.
Load a value from a future, cloning it on subsequent revisions after it is first returned. Re-initializes the loading future if the capture argument changes from previous revisions.
Calls load_with, never re-initializes the loading future, and clones the
returned value on each revision once the future has completed and returned.
Calls load_with but never re-initializes the loading future.
Load a value from the future returned by init whenever capture changes,
returning the result of calling with with the loaded value. Cancels the
running future after any revision during which this call was not made.
Runs init once per topo::CallId. The provided value
will always be cloned on subsequent calls unless first dropped from storage
before being re-initialized.
Caches init once in the current topo::CallId. Runs with on every
runtime::Revision.