[][src]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[src]

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

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

impl Runtime[src]

pub fn new() -> Self[src]

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

pub fn revision(&self) -> Revision[src]

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[src]

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)[src]

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)[src]

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

Trait Implementations

impl Default for Runtime[src]

Auto Trait Implementations

impl !RefUnwindSafe for Runtime

impl !Send for Runtime

impl !Sync for Runtime

impl Unpin for Runtime

impl !UnwindSafe for Runtime

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Downcast for T where
    T: Any

impl<T> Erased for T

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.