Behaviour for pluggable application runtime backends.
A runtime backend adapts an application style to Drafter's event loop: how an app produces its initial state, and how it turns the loop's messages — input events, named callbacks, timers, lifecycle hooks — into new state and effects. The loop, renderer, transport and timer machinery are the same whichever backend is in use.
An app selects one with use Drafter.App, runtime: MyBackend. Two ship with
Drafter: Drafter.Runtime.Callback, the default, taking mount/1 and
handle_event/2,3; and Drafter.Runtime.Reducer, taking init/1 and update/2.
render/1 is not part of this behaviour. The renderer calls the app's render/1
directly, so every backend requires the app to define it.
Summary
Types
A frame-pacing specification, as accepted by Drafter.Runtime.FrameClock.interval_for/1.
What a backend returns from handle_input/3 and handle_message/4.
Callbacks
Handle a raw input/framework event tuple, returning the app's event result.
Handle a named application message with its payload, returning the app's event result.
Produce the app's initial state from mount props (callback mount, reducer init).
Handle an out-of-band process message delivered to the loop.
Run the post-mount ready hook, returning possibly-updated state.
The app's preferred frame pacing, or nil to let the loop choose.
Hook invoked while scrolling is active (for scroll-driven state).
Hook invoked once scrolling settles.
Handle a fired timer.
Release what the app holds, once, as it stops for any reason, with its last state.
Functions
Resolve the runtime backend module for an app module.
The mount props carried by opts, as a map.
Normalize a backend shorthand or module to a backend module.
Types
@type app() :: module()
@type refresh_rate() :: pos_integer() | String.t() | :unlimited | nil
A frame-pacing specification, as accepted by Drafter.Runtime.FrameClock.interval_for/1.
nil means "no preference"; the loop then falls back to its own default.
@type result() :: term()
What a backend returns from handle_input/3 and handle_message/4.
Drafter.EventResult.parse/2 turns any of these into {state, actions, control},
so a backend may return a bare state, {:ok, state}, {:ok, state, actions},
{:noreply, state}, :handled, :unhandled, or {:stop, reason}.
@type state() :: term()
Callbacks
Handle a raw input/framework event tuple, returning the app's event result.
Handle a named application message with its payload, returning the app's event result.
Produce the app's initial state from mount props (callback mount, reducer init).
Handle an out-of-band process message delivered to the loop.
Run the post-mount ready hook, returning possibly-updated state.
@callback refresh_rate(app()) :: refresh_rate()
The app's preferred frame pacing, or nil to let the loop choose.
The value is passed to Drafter.Runtime.FrameClock.interval_for/1, so it may be a
millisecond integer, an fps string such as "30fps", "unlimited", or :unlimited.
Hook invoked while scrolling is active (for scroll-driven state).
Hook invoked once scrolling settles.
Handle a fired timer.
Release what the app holds, once, as it stops for any reason, with its last state.
Functions
Resolve the runtime backend module for an app module.
The first of these that is set wins: the calling process's
:drafter_runtime_override process-dictionary entry, which a shared session sets;
the app's own __runtime__/0, defined by use Drafter.App, runtime: ...; then
Drafter.Runtime.Callback. The result is passed through normalize/1, so
shorthand atoms are accepted in either place.
The mount props carried by opts, as a map.
Every entry point that starts an app — Drafter.run/2, a pushed nested session,
and Drafter.run_session/3 behind the ssh and telnet transports — carries mount
props under the single :props key. opts is that keyword list, or a map, which
is returned as the props themselves.
Returns %{} when :props is absent. The surrounding options are never treated
as props.
Examples
iex> Drafter.Runtime.mount_props(props: %{user_id: 7})
%{user_id: 7}
iex> Drafter.Runtime.mount_props(refresh_rate: "60fps")
%{}
iex> Drafter.Runtime.mount_props(props: [a: 1, b: 2])
%{a: 1, b: 2}
iex> Drafter.Runtime.mount_props(%{already: :props})
%{already: :props}Normalize a backend shorthand or module to a backend module.
Recognised shorthands are :callback, :reducer and :shared. Any other atom is
returned unchanged, so a backend module may be given directly.
Examples
iex> Drafter.Runtime.normalize(:callback)
Drafter.Runtime.Callback
iex> Drafter.Runtime.normalize(:reducer)
Drafter.Runtime.Reducer
iex> Drafter.Runtime.normalize(:shared)
Drafter.Runtime.Shared
iex> Drafter.Runtime.normalize(Drafter.Runtime.Callback)
Drafter.Runtime.Callback