Struct moxie::runtime::Runtime[][src]

pub struct Runtime { /* fields omitted */ }
Expand description

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

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

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

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

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.

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.

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

Trait Implementations

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait. Read more

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait. Read more

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s. Read more

Performs the conversion.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.