Expand description
The library that generated code links and a runtime implements.
ridl-rt defines, once, the vocabulary that a package generated from ridl
and a runtime agree on: identity, time and the envelope, samples, the
payload traits, the interaction descriptors, the ports, and the contract and
transport errors. It contains no runtime. A runtime is a separate crate that
implements the traits of the port module (ADR-0020 decision 6), and
generated code calls those traits without naming the runtime.
The crate is no_std, allocates nothing, contains no unsafe code, and has
no dependency in any feature combination. The cargo features flatbuffers,
proto3 and repr-c name the payload encodings. flatbuffers enables the
[flatbuffers] module, the reading and writing a generated
Payload<FlatBuffers> implementation shares; proto3 and repr-c enable
nothing in this version.
Every public item lives in one of six modules, or in the seventh that the
flatbuffers feature adds. Generated code names each
item by its full path, for example ridl_rt::sample::Sample, and imports
none, because several names here — Duration, Handler, Kind — are also
names in core or in application code.
§Where to start
Most of this crate is called by generated code, not by an application. An
application implements one generated Provider trait and calls generated
Client and Publisher methods; those methods call the ports here. So the
shortest path in is to read one interaction kind at a time, from the
generated side:
| To do this | The generated face gives you | Over this port |
|---|---|---|
| Read a signal | Client::<name> | port::SignalReader, returning sample::Sample |
| Publish a signal | Publisher::<name>, commit | port::SignalWriter |
| Receive an event | Client::subscribe_<name>, Client::next_event | port::EventSource |
| Raise an event | Publisher::<name> | port::EventSink |
| Call a command or a query | Client::<name>, returning a port::Correlation | port::Caller |
| Serve a command or a query | Provider, driven by the generated dispatch | port::Handler |
| Read a provisioned constant | nothing yet — call the port | port::FixedReader |
docs/technotes/ridl-rt-by-example.md in this repository walks that table
from top to bottom against concrete generated code, introducing each type
at the point where the generated code first needs it. The library’s own
as-built description is docs/design/ridl-rt.md.
Two properties hold everywhere and are worth knowing before reading any
individual item. No port method waits — every one returns immediately,
and a call’s outcome is retrieved separately through a
port::Correlation. And no port names a payload type — ports carry
interface numbers, ordinals and bytes, and the generated binding is what
encodes and decodes, through payload::Ref.
§How a runtime presents its ports
A runtime crate exposes one handle type per port role it implements — a
port role is one port trait — rather than one type implementing them all,
and it may also offer an aggregate handle covering the port set one
interface’s face needs. A generated face is built over one value
implementing at least the port traits its interface needs: the role handle
itself when the face needs exactly one, and an aggregate — the runtime’s,
or one the application writes over role handles — when it needs more,
because a generated Client may be bound over SignalReader,
EventSource and Caller at once. Either value reaches the face by value
or as a &mut borrow of itself, because every port trait is implemented
for &mut P and the &self-only traits also for &P. In a runtime whose
handles are used from more than one thread, a handle whose port traits all
take &self is Send + Sync, because several threads may read one store
at once, and a handle carrying a trait with a &mut self method is Send
and need not be Sync, because one thread drives each. No port trait here
carries Send or Sync as a supertrait, so a single-threaded no_std
runtime whose handles use Cell or RefCell internally is held to
neither; a runtime checks its own handles itself, with a compile-time
assertion. ADR-0021 decision 12 records this.
Modules§
- contract
- Identity, and the interaction descriptors generated code writes.
- encoding
- The payload encodings (ADR-0020 decisions 1 and 5).
- error
- The error strata of ridl §10 that a runtime reports.
- payload
- Encoding, verifying and decoding a payload.
- port
- The ports: the traits a runtime implements and generated code calls.
- sample
- Time, the envelope, and the values a read returns (ridl §3.1, §4.5, §9).