Crate moxie

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

runtime

Runtimes are the primary integration point between moxie and embedding environments.

testing

Utilities for testing moxie-based programs.

Structs

Commit

A read-only pointer to the value of a state variable at a particular revision.

Key

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

cache

Memoizes init at this callsite, cloning a cached Output if it exists and Input is the same as when the stored value was created.

cache_state

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_with

Cache the return of the init function.

load

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.

load_once

Calls load_with, never re-initializes the loading future, and clones the returned value on each revision once the future has completed and returned.

load_once_with

Calls load_with but never re-initializes the loading future.

load_with

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.

once

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.

once_with

Caches init once in the current topo::CallId. Runs with on every runtime::Revision.

state

Root a state variable at this callsite, returning a Key to the state variable.