Struct moxie::runtime::Runtime

pub struct Runtime { /* fields omitted */ }

A Runtime is the primary integration point between moxie and an embedder. Each independent instance is responsible for an event loop and tracks time using a Revision which it increments on each iteration of the loop. Owns the cache and state for a given context.

Key considerations

Event Loops

moxie assumes that it will be responsible for interfacing with or managing an event loop with the basic structure:

1. enter loop
2. present interface
3. wait for changes
4. goto (2)

Step (2) is implemented in Runtime::run_once, and the user code run by that method is expected to register the runtime for wakeups on future events. Step (3) is implemented by the embedder, waiting until the runtime’s change notification waker is invoked.

Change notifications

Each runtime should be provided with a std::task::Waker that will notify the embedding environment to run the loop again. This is done by calling Runtime::set_state_change_waker.

For scenarios without an obvious “main thread” this can be done for you by binding a root function to a RunLoop which implements std::future::Future and can be spawned as a task onto an executor. For more nuanced scenarios it can be necessary to write your own waker to ensure scheduling compatible with the embedding environment. By default a no-op waker is provided.

The most common way of notifying a runtime of a change is to update a state variable.

Caching

When a runtime is repeatedly invoking the same code for every Revision there’s likely to be a lot of repetitive work. This might be something complex like a slow computation over the set of visible items, or it might be something simple like using the same DOM node for a given button on every Revision.

While not strictly necessary to integrate moxie, much of the runtime’s potential value comes from identifying work that’s repeated across frames and storing it in the runtime’s cache instead of recomputing every time.

Internally the runtime hosts a dyn-cache instance which is garbage-collected at the end of each Revision. All cached values are stored there and evicted at the end of revisions where they went unused. This behavior also provides deterministic drop timing for values cached by the runtime.

Tasks

Each runtime expects to be able to spawn futures as async tasks, provided with Runtime::set_task_executor. By default a no-op spawner is provided.

Minimal Example

This example has no side effects in its root function, and doesn’t have any state variables which might require change notifications.

let mut rt = Runtime::new();
assert_eq!(rt.revision().0, 0);
for i in 1..10 {
    rt.run_once(|| ());
    assert_eq!(rt.revision(), Revision(i));
}

Implementations

impl Runtime

pub fn looped<Root, Out>(self, root: Root) -> RunLoop<Root> where
    Root: FnMut() -> Out, 

Returns this runtime bound with a specific root function it will run in a loop.

impl Runtime

pub fn new() -> Self

Construct a new Runtime with blank storage and no external waker or task executor.

pub fn revision(&self) -> Revision

The current revision of the runtime, or how many times run_once has been invoked.

pub fn run_once<Out>(&mut self, op: impl FnOnce() -> Out) -> Out

Runs the root closure once with access to the runtime context, increments the runtime’s Revision, and drops any cached values which were not marked alive.

pub fn set_state_change_waker(&mut self, wk: Waker)

Sets the std::task::Waker which will be called when state variables receive commits. By default the runtime no-ops on a state change, which is probably the desired behavior if the embedding system will call Runtime::run_once on a regular interval regardless.

pub fn set_task_executor(&mut self, sp: impl LocalSpawn + 'static)

Sets the executor that will be used to spawn normal priority tasks.

Trait Implementations

impl Default for Runtime

fn default() -> Runtime

Returns the “default value” for a type.