Expand description
The machine-readable schemas the compiler and the runtime both read.
There are two of them, and they are here for the same reason. The Host API
schema, below, is what a host module declares about itself; builtins is
what the language declares about its own types. Neither could live in
cove-runtime or in cove-sema, because each is read by both and the
dependency between those two runs one way.
The two keep separate vocabularies on purpose. A host operation’s
signature is monomorphic, so HostType has no type parameters and needs
none; a builtin’s is generic, receiver-relative, and sometimes
higher-order, so builtins::BuiltinType has all three and a host
signature would have no use for them. builtins argues that at length.
ADR 0001 states what the Host API half has to carry:
A machine-readable Host API schema is shared by the compiler, runtime, and CLI. Each operation describes its argument, result, and error types; capability; serialization and resource ownership; cancellation and recordability; and whether it is a read, reversible write, or irreversible write.
and the Language Card adds the sentence that makes the schema load-bearing for tasks: “Host resources declare task-safety in their Host API schema.”
“Shared by the compiler, runtime, and CLI” is why this is a crate of its
own and not a module of cove-runtime. cove-sema checks a host call
against the same description the boundary dispatches it through, and the
dependency between the two runs one way: the compiler must not gain a
dependency on the runtime to say what it already knows. So the description
moved below both of them, where each can read it, and cove-runtime
re-exports it so a host written against the runtime still names one crate.
Two lists that must agree and cannot see each other drift silently, which
this repository has already paid for once; the fix that scales is one
list.
A schema entry is Rust data, not a parsed declaration, because a host is
written in Rust: HostApi::schema returns a 'static table, so a module
and its declaration of itself cannot drift apart at run time. The shipped
hosts’ tables are in hosts, and the module that implements each of
them returns the table from there rather than one of its own.
Only the parts of ADR 0001’s list that something reads are modelled here. Serialization is left out: every value that crosses the boundary is an ordinary runtime value, and a field nothing consults is a claim nothing checks.
Resource ownership is no longer among the omissions. A host may declare
types of its own — TypeSchema for the ones that are plain data, and
ResourceSchema for the ones the host keeps on the far side of the
boundary — and ADR 0013 makes the second of those the whole of a resource
handle’s contract: which operations it answers, what capability each of
them needs, and whether the handle may cross a task boundary.
What a value has to be for a declared type to admit it is not here. That
question needs values, which this crate has none of; cove_runtime::schema
answers it, on the side of the boundary where values live.
Re-exports§
pub use builtins::builtin;pub use builtins::free_builtin;pub use builtins::is_builtin_type;pub use hosts::module;pub use hosts::shipped;pub use hosts::HostSchemas;
Modules§
- builtins
- What the builtin types declare about themselves.
- hosts
- What the host modules the toolchain ships declare about themselves.
Structs§
- Field
Schema - One field of a host type.
- Module
Schema - The name, capability, operations, types, and resources of one host module.
- Operation
Schema - One operation of one host module.
- Resource
Schema - One kind of host resource: a value the host owns and Cove only names.
- Schema
Fault - A schema that declares something no value can be.
- Type
Schema - The shape of one type a host declares.