MDL's runtime for Elixir: open an artifact store morphc built, decode
telemetry, encode commands, describe the build, and look up which asset
a native id is. It calls the runtime every binding calls (spec/api.md),
through a native library, and holds no MDL semantics of its own.
{:ok, mdl} = MDL.open("store", bindings: File.read!("bindings.toml"))
{:ok, decoded} =
MDL.decode(mdl, "sat", %{
payload: payload,
metadata: %{"apid" => 100},
ground_time: System.os_time(:nanosecond)
})
for %MDL.Sample{param: param, value: value, quality: :good} <- decoded.samples do
{param, value}
end
{:ok, command} =
MDL.encode(mdl, "sat", %{
set: "sat_v1",
command: "eps.set_mode",
arguments: %{"mode" => "SAFE"}
})Values
Results use Elixir's own values:
- The results' fixed shapes are structs (
MDL.Decoded,MDL.Sample,MDL.Encoded,MDL.Route,MDL.Error,MDL.Problem,MDL.Vec3,MDL.Quat), and MDL's own names in them are atoms: a quality, a frame, an error's code, an event time's kind, a time unit. - Everything that comes from definitions or messages is a string: param and entry names, paths, units, state names, metadata keys, the record's keys. A node that keeps reloading stores never grows its atom table.
- Integers are of any size. NaN and the infinities, which the BEAM's
floats can't hold, are
:nan,:infinityand:neg_infinity. - Text and bytes are both binaries; a param's or field's type, which
describe/1gives, says which. A bytes argument toencode/3is{:bytes, binary}. - An instant is an integer: nanoseconds since 1970-01-01T00:00:00Z,
every day 86,400 seconds.
DateTimeholds microseconds.
Errors
Every operation returns {:ok, result} or {:error, %MDL.Error{}},
whose :code names the problem and is stable across releases. An
argument of the wrong shape (a payload that isn't a binary, a metadata
key that isn't a string) raises ArgumentError.
Handles and scheduling
A handle is immutable and may be used by any number of processes at
once: store it where every process can reach it (:persistent_term, an
ETS table, a process's state). Opening the store again gives a new
handle; an older one keeps working, on the build it opened, until it's
garbage collected.
Every function that does MDL's work runs on a dirty CPU scheduler, so no
definition or payload, however large, holds up the BEAM's normal
schedulers. The switch costs a few microseconds a call; decode_many/3
pays it once for a batch.
Summary
Types
An argument's value: bytes are {:bytes, binary}, text a string.
When a message's values were taken: its ground time, when the packet gives none; an instant the packet gives; or a count since the asset booted, which isn't an instant until correlated.
A family's name.
A float, or NaN or an infinity.
A composite's frame: its IR name, ECI_J2000, in lower case.
An opened store.
Nanoseconds since 1970-01-01T00:00:00Z, every day 86,400 seconds.
A message: its payload (a JSON family's is the document's UTF-8 text), the metadata the link delivers with it, and when the ground received it.
Metadata a link delivers with a payload, by name.
What a family's alias locator reads: an integer or a string.
Whether a value can be trusted; any but :good is the raw value.
A command to encode: the set that encodes it, the catalog command, its arguments by name, and the native id of the asset it's sent to, for a packet that writes it.
An operation's result.
A decoded value: a record's, a sample's or an engineering value's.
Functions
The native id that is asset in family at at, with its binding
(spec/api.md section 2.6): where a command to the asset goes. nil when
no native id is the asset then; :ambiguous_asset when several are.
What native_id of family is at at (spec/api.md section 2.6), as a
message received then would resolve it: its binding, or without bindings
the asset it stands for; nil when it's no asset then.
Decodes a message family sent (spec/api.md section 2.2): routes it to
an asset and a set, identifies its packet, and gives its samples.
Decodes each message, in order (spec/api.md section 2.3): one result per message, one message's error not stopping the others. One call for the batch, so the switch to a dirty scheduler is paid once.
Describes the build (spec/api.md section 3.3): the catalog, each family
and each set as the IR has them, with their digests, and where each
entry of a binary set can be. The description is maps with string keys,
as the IR's JSON is: "format", "catalog", "families" and "sets".
Encodes a catalog command as one of family's sets' command packets
(spec/api.md section 2.4), its arguments checked against their types,
states, ranges and lists.
Opens the store in dir (spec/api.md section 2.1).
Opens a store given as its files' bytes: the manifest's, and each
artifact's, which are found by their own identity and need no names.
Takes the options open/2 takes.
What the handle's bindings say that its build doesn't have: a set it lacks, a set named for a family whose version locator chooses. The messages these affect are refused when decoded, with their own codes.
The handle's build with other bindings (their text), or none (nil),
without reading or assembling the build again.
Types
@type argument() :: integer() | float() | :nan | :infinity | :neg_infinity | boolean() | String.t() | {:bytes, binary()} | [argument()]
An argument's value: bytes are {:bytes, binary}, text a string.
@type event_time() :: {:ground, instant()} | {:at, instant()} | {:since_boot, non_neg_integer(), :s | :ms | :us | :ns}
When a message's values were taken: its ground time, when the packet gives none; an instant the packet gives; or a count since the asset booted, which isn't an instant until correlated.
@type family() :: String.t()
A family's name.
@type float_value() :: float() | :nan | :infinity | :neg_infinity
A float, or NaN or an infinity.
@type frame() :: :ecef | :eci_j2000 | :body | :ned | :enu | :geodetic
A composite's frame: its IR name, ECI_J2000, in lower case.
@opaque handle()
An opened store.
@type instant() :: integer()
Nanoseconds since 1970-01-01T00:00:00Z, every day 86,400 seconds.
@type message() :: %{ :payload => binary(), :ground_time => instant(), optional(:metadata) => metadata() }
A message: its payload (a JSON family's is the document's UTF-8 text), the metadata the link delivers with it, and when the ground received it.
Metadata a link delivers with a payload, by name.
What a family's alias locator reads: an integer or a string.
@type quality() ::
:good
| :invalid
| :unknown_state
| :out_of_calibration
| :out_of_range
| :non_finite
Whether a value can be trusted; any but :good is the raw value.
@type request() :: %{ :set => String.t(), :command => String.t(), optional(:arguments) => %{optional(String.t()) => argument()}, optional(:native_id) => native_id() | nil }
A command to encode: the set that encodes it, the catalog command, its arguments by name, and the native id of the asset it's sent to, for a packet that writes it.
@type result(ok) :: {:ok, ok} | {:error, MDL.Error.t()}
An operation's result.
@type value() :: integer() | float_value() | boolean() | binary() | MDL.Vec3.t() | MDL.Quat.t() | nil | [value()] | %{optional(String.t()) => value()}
A decoded value: a record's, a sample's or an engineering value's.
Functions
The native id that is asset in family at at, with its binding
(spec/api.md section 2.6): where a command to the asset goes. nil when
no native id is the asset then; :ambiguous_asset when several are.
What native_id of family is at at (spec/api.md section 2.6), as a
message received then would resolve it: its binding, or without bindings
the asset it stands for; nil when it's no asset then.
@spec decode(handle(), family(), message()) :: result(MDL.Decoded.t())
Decodes a message family sent (spec/api.md section 2.2): routes it to
an asset and a set, identifies its packet, and gives its samples.
@spec decode_many(handle(), family(), [message()]) :: [result(MDL.Decoded.t())]
Decodes each message, in order (spec/api.md section 2.3): one result per message, one message's error not stopping the others. One call for the batch, so the switch to a dirty scheduler is paid once.
Describes the build (spec/api.md section 3.3): the catalog, each family
and each set as the IR has them, with their digests, and where each
entry of a binary set can be. The description is maps with string keys,
as the IR's JSON is: "format", "catalog", "families" and "sets".
@spec encode(handle(), family(), request()) :: result(MDL.Encoded.t())
Encodes a catalog command as one of family's sets' command packets
(spec/api.md section 2.4), its arguments checked against their types,
states, ranges and lists.
Opens the store in dir (spec/api.md section 2.1).
Options:
:bindings: the text of a bindings file, which names the asset each native id is and the set that decodes it. Without it, each native id stands for an asset of its own.
Bindings that can't be read refuse the open. Anything else they say that
the build doesn't have is a warning (warnings/1), and the messages it
affects are refused when decoded.
Opens a store given as its files' bytes: the manifest's, and each
artifact's, which are found by their own identity and need no names.
Takes the options open/2 takes.
@spec warnings(handle()) :: [MDL.Problem.t()]
What the handle's bindings say that its build doesn't have: a set it lacks, a set named for a family whose version locator chooses. The messages these affect are refused when decoded, with their own codes.
The handle's build with other bindings (their text), or none (nil),
without reading or assembling the build again.