compiler 0.0.2-preview.1
The Zena self-hosted compiler
compiler#
The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).
Usage#
Parsing a Single File#
Use compiler/parser to parse Zena source text into an AST (Module):
import { parse } from 'compiler/parser';
let ast = parse('export let answer = 42;', 'example.zena');
Loading and Checking a Program#
Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:
import {
createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';
let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
stdlibRoot,
packages,
});
let result = await compiler.compile({
entry: '/workspace/main.zena',
target: 'host',
});
let checked = checkCompilation(result);
Compiling a File to WebAssembly#
Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:
import { compileFile } from 'compiler/compile-file';
let ok = await compileFile({
entry: 'src/main.zena',
outPath: 'out/main.wasm',
stdlibRoot: '/stdlib',
});
Libraries#
compiler/compiler/compiler— compiler entry point (Compiler,createCompiler,checkCompilation,ProgramCheckResult)compiler/compile-file— end-to-end file compilation (compileFile,CompileFileOptions)compiler/tokenizer— lexer and token definitions (tokenize,Token,TokenType)compiler/parser— recursive-descent parser (parse,Parser)compiler/ast— AST node definitions (Node,Module,Statement,Expression,TypeAnnotation)compiler/visitor— AST traversal helpers (walk,Visitor)compiler/scope— lexical scope and symbol resolution (ScopeBuilder,ScopeResult,Symbol)compiler/checker— static type checker (checkModule,CheckResult)compiler/semantic-model— semantic queries over a checked module (SemanticModel)compiler/types— compiler type representations (Type,ClassType,FunctionType,typeToString)compiler/diagnostics— compiler diagnostics and source spans (Diagnostic,DiagnosticCode,DiagnosticSeverity,SourceSpan)compiler/package-manifest—zena-package.jsonmanifest and workspace loader (loadWorkspace,loadPackageMap)compiler/module-resolver— package and relative module specifier resolution (ModuleResolver,PackageConfig)compiler/library-loader— module graph loader (LibraryLoader,CompilerHost,SourceFile)compiler/codegen/binary-generator— WebAssembly GC binary emitter (BinaryGenerator)compiler/codegen/wat-generator— WebAssembly Text (WAT) emitter (WatGenerator)
License#
MIT
164.8 KiB
Raw
/**
* WIT-typed modules, synthesized: the source text behind an
* `import {now} from 'wasi:clocks/monotonic-clock'`.
*
* A WIT-backed package (`{"wit": "./path"}` in the manifest) resolves
* its modules to `wit:<root>#<namespace>:<interface-path>` canonical
* paths, and the compiler host answers `readFile` for those by calling
* `synthesizeWitModule` here: read the root's WIT back through the
* host, parse it, find the interface, and render its declarations as
* Zena typed *from the WIT* — the checker then sees the interface's
* real signatures rather than whatever an author transcribed.
*
* This module is imported by the drivers (the CLI's host, the test
* hosts), never by compiler-lib code — the same edge as
* `wit-imports.zena`, and for the same reason: it keeps the WIT parser
* out of the module graphs of hosts that do not serve WIT-backed
* packages, like the language service.
*
* The rendered surface, per Part 5's mapping
* (docs/design/component-model.md):
*
* - Named types are declared: `enum` → Zena enum with explicit
* ordinals, `flags` → distinct u32 with per-label constants,
* `record` → case class, `variant` → sealed case-class hierarchy
* (case classes prefixed with the variant's name, because two
* variants in one interface may declare same-named cases).
* - A flat-scalar function is one `@external` declaration. Staged
* parameters (`string`, `list<u8>`) and lifted results ride a
* wrapper over `zena:wasi`, as before.
* - A result that flattens past one core value spills: the raw call
* takes a return-area address, the canonical ABI writes the value
* there with our `realloc`, and generated lift code reads it out at
* the canonical offsets — records, variants, options, tuples and
* lists of all of these, recursively, freeing every host-written
* buffer as it goes. A top-level `result<T, E>` lifts into the
* inline `Result<T, E>`; a nested one waits.
* - Parameters spill the other way: past sixteen core values on a
* synchronous call, or four on an asynchronous one (a method's
* `self` handle counts), the wrapper stages one buffer laid out
* like a record, stores each parameter at its aligned offset, and
* the raw call takes that address as its one argument. The buffer
* is freed with the wrapper's other staging, after the call — or,
* for an async lowering, after the subtask has returned.
*
* - `stream<u8>` in any position is `zena:stream`'s `Stream<u8>`: one
* end-handle on the wire, connected by `zena:wasi`'s
* pumps (`lowerByteStream` going in, `liftByteStream` coming out).
* - `future<T>` in any position is a `Future`: one end-handle on the
* wire, moved by generated per-payload-type helpers over the
* `future.*` canon builtins (each declared at the payload's own
* component type, `future:<interface>#<payload>`). A `result`
* payload is a stored `Result`, and a bare result arm — `result<_, E>`
* anywhere — is a `void` lane filled by `witUnit()`.
*
* A function whose signature needs more — non-u8 stream elements,
* bare futures, variant payloads joining across core types — is
* listed in the synthesized module's header comment with its reason,
* and importing it reports a missing export.
*/
import { StringBuilder, growable } from 'zena:core';
import { parse, parseSyntax } from 'zena-lang:wit-parser';
import {
findInterface, findInterfaceOrNull, FoundInterface
} from 'zena-lang:wit-parser/document';
import { expandedWorldItems } from 'zena-lang:wit-parser/component-encoder';
import {
InterfaceItem, InterfaceItemTag, NamedFunc, Type, TypeTag, TypeDef,
TypeDefTag, Id, EnumCaseDef, FlagDef, Field, Case, ResourceFunc,
ResourceFuncTag, Ast, PackageName, Use, UsePath, IdUsePath,
PackageUsePath, UsePathTag, AstItemTag, WorldDef, WorldItemTag, Export,
ExternKindTag, Func
} from 'zena-lang:wit-parser/parser';
import { Module } from './ast.zena';
import { CompilerHost } from './library-loader.zena';
import { readWitSource } from './wit-source.zena';
import { withWasiPackages } from './codegen/wit-imports.zena';
import {
ComponentEntryWrapper, componentEntryPathFor,
componentEntrySpecifierFor, componentExportSuffix, resourceWrapperBase,
mainWrapperResultOf, mainWrapperAbiImports, hasAsyncMain, renderMainWrapper,
renderWrapperHeader, exportedFunctionIsAsync, classHasStatic,
componentSyncExportSuffix
} from './component-entry.zena';
import { zena, emit, ZenaTemplate } from './code-template.zena';
/** Whether `path` is a synthesized WIT module's canonical path. */
export function isWitModulePath(path: String): boolean {
return path.startsWith("wit:");
}
/**
* The WIT source the module being synthesized was parsed from. A
* future's canon type spelling carries its payload's source text,
* and classification — which sees only nodes — slices it out by span.
*/
var currentWitSource = "";
/**
* The parsed document and the package whose interface classification
* is currently reading — a `use` hop switches the package (a bare
* `use foo` resolves against the interface's own package, and a
* nested package's is not the document's main one).
*/
var currentAst: Ast | null = null;
/** The entry module's syntax, for what implements each export. */
var currentEntryAst: Module | null = null;
/**
* The document last parsed, by its text: every synthesized module of
* a program reads the same spliced corpus, and parsing it is most of
* a synthesis. The AST is only read, so one serves every module.
*/
var memoSource = "";
var memoAst: Ast | null = null;
function parsedWit(source: String) {
let cached = memoAst;
if (cached != null && memoSource == source) {
return cached;
}
let ast = parse(source);
memoSource = source;
memoAst = ast;
return ast;
}
var currentPackage: PackageName | null = null;
/**
* Which synthesized module declares the types classification meets:
* the unversioned `ns:pkg/iface` specifier. `selfSpecifier` is the
* module being synthesized; `currentSpecifier` tracks `use` hops, and
* a named type minted under a foreign specifier owes an import line
* from that sibling module rather than a local declaration.
*/
var selfSpecifier = "";
var currentSpecifier = "";
/**
* The interfaces whose resources render as `resource class` — an
* `own` is `Own<T>`, released at scope exit unless moved, a `borrow`
* is `Borrow<T>`, and a use after a move is a compile error — rather
* than as a `Disposable` class with a runtime moved flag that the
* program must `using` or dispose by hand. Every interface should be
* here; the list exists because the switch changes every signature a
* consumer sees, so it moves one interface at a time, as its
* consumers in the standard library and the packages migrate
* (docs/design/component-model.md, Part 6). An interface whose
* consumer the checked-in bootstrap compiles (`wasi:filesystem`, through
* `zena:fs` in the compiler's own closure) can only join after a
* reseed carries this rendering. Keyed by the specifier without its
* version, the form `currentSpecifier` carries.
*/
let ownedResourceSpecifiers = [
'zena:host/process', 'zena:host/wasm', 'wasi:filesystem/types',
'wasi:http/types', 'zena:host/http-server', 'zena:host/terminal'
];
function rendersAsResourceClass(specifier: String): boolean {
for (let s in ownedResourceSpecifiers) {
if (s == specifier) { return true; }
}
return false;
}
/** The `zena:core` import line for the handle spellings a module used,
* or "" when it used none. */
function handleImports(uses: SynthUses) {
let names = new Array<String>();
if (uses.ownHandle) { names.push("Own"); }
if (uses.borrowHandle) { names.push("Borrow"); }
if (uses.unmanagedHandle) { names.push("Unmanaged"); }
if (uses.disown) { names.push("disown"); }
if (names.length == 0) {
return "";
}
var list = names[0];
for (var i = 1; i < names.length; i += 1) {
list = `${list}, ${names[i]}`;
}
return `import { ${list} } from 'zena:core';\n`;
}
/** One imported type name owed to a sibling synthesized module. */
final class UsedTypeImport {
specifier: String;
name: String;
new(this.specifier, this.name);
}
var usedTypeImports = new Array<UsedTypeImport>();
/**
* An interface the export wrapper being written provides, by the
* specifier its types classify under and the qualified name the canon
* builtins spell. A resource declared in one is the program's own
* class, exported through the wrapper, rather than a handle class of
* a synthesized module.
*/
final class ExportedInterface {
specifier: String;
qualified: String;
new(this.specifier, this.qualified);
}
var exportedInterfaces = new Array<ExportedInterface>();
/** The qualified name of the exported interface at `specifier`, or
* "" when the wrapper does not export it. */
function exportedQualifiedOf(specifier: String) {
for (let e in exportedInterfaces) {
if (e.specifier == specifier) { return e.qualified; }
}
return "";
}
/**
* A resource the program provides: its class (imported from the
* entry), the WIT name (the table helpers are named after it), and
* the interface declaring it (the canon `resource.new` names its
* type).
*/
final class ProgramResource {
className: String;
witName: String;
qualified: String;
new(this.className, this.witName, this.qualified);
}
var programResources = new Array<ProgramResource>();
function noteProgramResource(className: String, witName: String,
qualified: String) {
for (let existing in programResources) {
if (existing.className == className) { return; }
}
programResources.push(new ProgramResource(className, witName, qualified));
}
function noteUsedImport(specifier: String, name: String) {
for (let existing in usedTypeImports) {
if (existing.specifier == specifier && existing.name == name) {
return;
}
}
usedTypeImports.push(new UsedTypeImport(specifier, name));
}
/** A span's source text with whitespace runs collapsed to one space,
* so it can ride inside a generated string literal. */
function spanText(start: i32, end: i32) {
var out = "";
var pendingSpace = false;
for (var i = start; i < end; i += 1) {
let c = currentWitSource.getByteAt(i);
if (c == 32 || c == 9 || c == 10 || c == 13) {
pendingSpace = out != "";
continue;
}
if (pendingSpace) {
out = out + " ";
pendingSpace = false;
}
out = out + currentWitSource.sliceBytes(i, i + 1);
}
return out;
}
/** How a WIT type crosses the boundary in the rendered slice. */
enum TyKind {
/** One core value, passed through: the Zena spelling is `scalar`. */
Scalar,
/** `string`: `(ptr, len)` on the wire. */
Str,
/** `list<u8>`: the same wire shape as a string. */
BytesList,
/** `list<T>` for any other liftable `T`. */
ListT,
/** A WIT `enum`: one discriminant on the wire, a Zena enum here. */
Enumeration,
/** A WIT `flags`: one bitset word on the wire, a distinct u32 here. */
Flags,
/** A WIT `record`: a case class. */
RecordT,
/** A WIT `variant`: a sealed case-class hierarchy. */
VariantT,
/** `option<T>`: `Option<T>`. */
OptionT,
/** `result<T, E>`: `inline Result<T, E>` at top level. */
ResultT,
/** `tuple<...>`: an inline tuple. */
TupleT,
/** A resource handle (`own`, `borrow`, or a bare resource name):
* one i32 index on the wire, a Disposable wrapper class here. */
ResourceH,
/** `stream<u8>`: one end-handle i32 on the wire, `zena:stream`'s
* `Stream<u8>` here, pumped by `zena:wasi`. */
StreamH,
/** `future<T>`: one end-handle i32 on the wire, a `Future` here,
* read and written by generated per-payload-type helpers. */
FutureH,
/** Waits on the interop stages; `reason` says which. */
Unsupported
}
/**
* A classified WIT type with its canonical layout: `size`/`align` are
* the canonical ABI's, `flats` the count of core values the type
* flattens to. Children: a record's or tuple's members, a list's
* element, an option's inner, a result's ok/err, a variant's payloads
* — with the void sentinel standing in for an absent payload.
*/
final class Ty {
kind: TyKind;
/** The Zena spelling of a Scalar; "" otherwise. */
scalar: String;
/** The synthesized Zena type name of a named type. */
typeName: String;
reason: String;
/** Enum/variant case count, or flags label count. */
var caseCount = 0;
children = new Array<Ty>();
/** Record field names (camelCase) or variant case names (Pascal,
* already prefixed with the variant's own name). */
childNames = new Array<String>();
var size = 0;
var align = 1;
var flats = 0;
/** ResourceH only: whether this position borrows rather than owns.
* Everywhere else a resource in value position is an implicit
* `own`, which consumes — the wrapper is marked moved when lowered. */
var isBorrow = false;
/** ResourceH only: whether the resource is the program's own — one
* an exported interface declares, implemented by the program's class
* — rather than a handle class of a synthesized module. Its wire
* form is the representation, an index into the wrapper's table. */
var isProgram = false;
/** ResourceH only: the resource's WIT name, which the wrapper's
* table helpers are named after. */
var resourceName = "";
/** ResourceH only: whether the handle class is a `resource class`,
* so that this position spells a handle — `Own<T>` for an own in a
* bare position or a tuple member there, `Borrow<T>` for a borrow,
* `Unmanaged<T>` for an own inside a list, record or variant
* payload, which cannot hold an owner. See `rendersAsResourceClass`. */
var ownedClass = false;
/** Whether this type sits inside a list, record or variant payload,
* directly or through tuples, options and results (`markInAggregate`):
* an aggregate's member cannot carry an affine type, so an own handle
* there is `Unmanaged<T>`, for the program to `adopt`. */
var inAggregate = false;
/** FutureH only: the payload's WIT source text, whitespace
* collapsed — the canon type spelling the generated builtins name. */
var witText = "";
new(this.kind, this.scalar = "", this.typeName = "", this.reason = "");
}
function unsupported(reason: String) {
return new Ty(TyKind.Unsupported, "", "", reason);
}
/**
* Mark `ty` as a list element, record field or variant payload, along
* with the members of a tuple, option or result it is, which sit in
* the same aggregate. A tuple is not an aggregate itself: a tuple in a
* bare position, such as a stream element or a function's result,
* carries owners (`(Own<Request>, Own<ResponseWriter>)`).
*/
function markInAggregate(ty: Ty): void {
ty.inAggregate = true;
if (ty.kind == TyKind.TupleT || ty.kind == TyKind.OptionT ||
ty.kind == TyKind.ResultT) {
for (let child in ty.children) {
markInAggregate(child);
}
}
}
/**
* A named type just classified: when it belongs to another interface
* (the classification is inside a `use` hop), its Zena declarations
* live in that interface's synthesized module, so the current module
* imports them — the sealed base and every case, for a variant.
*/
function noteNamedType(ty: Ty) {
if (currentSpecifier == selfSpecifier || ty.typeName == "") {
return;
}
noteUsedImport(currentSpecifier, ty.typeName);
if (ty.kind == TyKind.VariantT) {
for (let caseName in ty.childNames) {
noteUsedImport(currentSpecifier, caseName);
}
}
}
/** The stand-in for an absent variant payload or result arm. */
function voidTy() {
let ty = new Ty(TyKind.Scalar, "void");
ty.size = 0;
ty.align = 1;
ty.flats = 0;
return ty;
}
function isVoid(ty: Ty) {
return ty.kind == TyKind.Scalar && ty.scalar == "void";
}
/** `x` rounded up to a power-of-two alignment `a`. */
function alignTo(x: i32, a: i32) {
if (a <= 1) {
return x;
}
let r = x & (a - 1);
return if (r == 0) x else x + a - r;
}
/** The canonical discriminant size for `count` cases. */
function discSize(count: i32): i32 {
if (count <= 256) { return 1; }
if (count <= 65536) { return 2; }
return 4;
}
function scalarTy(spelling: String, size: i32) {
let ty = new Ty(TyKind.Scalar, spelling);
ty.size = size;
ty.align = size;
ty.flats = 1;
return ty;
}
function pairTy(kind: TyKind) {
let ty = new Ty(kind);
ty.size = 8;
ty.align = 4;
ty.flats = 2;
return ty;
}
/** Lay out a variant-shaped type: a discriminant then the aligned
* payload area, sized for the largest case. */
function layoutVariant(ty: Ty, count: i32) {
let disc = discSize(count);
var payloadAlign = 1;
var payloadSize = 0;
var maxFlats = 0;
for (let child in ty.children) {
if (child.align > payloadAlign) { payloadAlign = child.align; }
if (child.size > payloadSize) { payloadSize = child.size; }
if (child.flats > maxFlats) { maxFlats = child.flats; }
}
ty.align = if (disc > payloadAlign) disc else payloadAlign;
ty.size = alignTo(alignTo(disc, payloadAlign) + payloadSize, ty.align);
ty.flats = 1 + maxFlats;
ty.caseCount = count;
}
/** A variant-shaped type's payload offset. */
function payloadOffset(ty: Ty) {
var payloadAlign = 1;
for (let child in ty.children) {
if (child.align > payloadAlign) { payloadAlign = child.align; }
}
return alignTo(discSize(ty.caseCount), payloadAlign);
}
/** Lay out a record-shaped type: fields at their aligned offsets. */
function layoutRecord(ty: Ty) {
var offset = 0;
var maxAlign = 1;
var flats = 0;
for (let child in ty.children) {
if (child.align > maxAlign) { maxAlign = child.align; }
offset = alignTo(offset, child.align) + child.size;
flats += child.flats;
}
ty.align = maxAlign;
ty.size = alignTo(offset, maxAlign);
ty.flats = flats;
}
/** A record-shaped type's field offsets, in declaration order. */
function fieldOffsets(ty: Ty) {
let offsets = new Array<i32>();
var offset = 0;
for (let child in ty.children) {
offset = alignTo(offset, child.align);
offsets.push(offset);
offset += child.size;
}
return offsets;
}
/**
* Classify a WIT type for rendering, with its canonical layout. A
* named type resolves through the interface's own declarations —
* aliases transparently, enums/flags/records/variants to their
* synthesized Zena types.
*/
function classifyType(t: Type, ifaceItems: GrowableArray<InterfaceItem>): Ty {
match (t.tag) {
case TypeTag.Bool: { return scalarTy("boolean", 1); }
case TypeTag.U8: { return scalarTy("u8", 1); }
case TypeTag.U16: { return scalarTy("u16", 2); }
case TypeTag.U32: { return scalarTy("u32", 4); }
case TypeTag.U64: { return scalarTy("u64", 8); }
case TypeTag.S8: { return scalarTy("i8", 1); }
case TypeTag.S16: { return scalarTy("i16", 2); }
case TypeTag.S32: { return scalarTy("i32", 4); }
case TypeTag.S64: { return scalarTy("i64", 8); }
case TypeTag.F32: { return scalarTy("f32", 4); }
case TypeTag.F64: { return scalarTy("f64", 8); }
case _: {}
}
if (t.tag == TypeTag.String) {
return pairTy(TyKind.Str);
}
if (t.tag == TypeTag.List) {
if (t.fixedLength >= 0) {
return unsupported("fixed-length lists wait on the interop stages");
}
let element = classifyType(t.inner as Type, ifaceItems);
if (element.kind == TyKind.Unsupported) {
return element;
}
if (element.kind == TyKind.Scalar && element.scalar == "u8") {
return pairTy(TyKind.BytesList);
}
let ty = pairTy(TyKind.ListT);
markInAggregate(element);
ty.children.push(element);
return ty;
}
if (t.tag == TypeTag.Option) {
let inner = classifyType(t.inner as Type, ifaceItems);
if (inner.kind == TyKind.Unsupported) {
return inner;
}
let ty = new Ty(TyKind.OptionT);
ty.children.push(inner);
layoutVariant(ty, 2);
return ty;
}
if (t.tag == TypeTag.Result) {
let ok = t.okType;
let err = t.errType;
let okTy = if (ok == null) voidTy()
else classifyType(ok as Type, ifaceItems);
let errTy = if (err == null) voidTy()
else classifyType(err as Type, ifaceItems);
if (okTy.kind == TyKind.Unsupported) { return okTy; }
if (errTy.kind == TyKind.Unsupported) { return errTy; }
let ty = new Ty(TyKind.ResultT);
ty.children.push(okTy);
ty.children.push(errTy);
layoutVariant(ty, 2);
return ty;
}
if (t.tag == TypeTag.Tuple) {
let ty = new Ty(TyKind.TupleT);
for (let member in t.types as GrowableArray<Type>) {
let child = classifyType(member, ifaceItems);
if (child.kind == TyKind.Unsupported) {
return child;
}
ty.children.push(child);
}
layoutRecord(ty);
return ty;
}
if (t.tag == TypeTag.Stream) {
let element = t.inner;
if (element == null) {
return unsupported("a bare stream waits on the interop stages");
}
let elementType = element as Type;
let el = classifyType(elementType, ifaceItems);
if (el.kind == TyKind.Unsupported) {
return el;
}
let ty = new Ty(TyKind.StreamH);
ty.size = 4;
ty.align = 4;
ty.flats = 1;
if (el.kind == TyKind.Scalar && el.scalar == "u8") {
// Bytes: `zena:wasi`'s pumps, with no element marshaling.
return ty;
}
// Any other element rides a generated pair of pumps that lift and
// lower each element through memory, so the element must move
// both ways.
let unliftable = liftBlocker(el, true);
if (unliftable != "") {
return unsupported(unliftable);
}
let unlowerable = lowerBlocker(el);
if (unlowerable != "") {
return unsupported(unlowerable);
}
ty.children.push(el);
ty.witText = spanText(elementType.span.start, elementType.span.end);
return ty;
}
if (t.tag == TypeTag.Future) {
let inner = t.inner;
if (inner == null) {
return unsupported("a bare future waits on the interop stages");
}
let payloadType = inner as Type;
let payload = classifyType(payloadType, ifaceItems);
if (payload.kind == TyKind.Unsupported) {
return payload;
}
let ty = new Ty(TyKind.FutureH);
ty.children.push(payload);
ty.size = 4;
ty.align = 4;
ty.flats = 1;
ty.witText = spanText(payloadType.span.start, payloadType.span.end);
return ty;
}
if (t.tag == TypeTag.Own || t.tag == TypeTag.Borrow) {
let inner = t.inner as Type;
if (inner.tag != TypeTag.Name) {
return unsupported("own/borrow of an unnamed type");
}
let resolved = classifyNamed((inner.name as Id).name, ifaceItems);
if (resolved.kind != TyKind.ResourceH &&
resolved.kind != TyKind.Unsupported) {
return unsupported("own/borrow of a non-resource type");
}
if (resolved.kind == TyKind.ResourceH) {
resolved.isBorrow = t.tag == TypeTag.Borrow;
}
return resolved;
}
if (t.tag == TypeTag.Name) {
return classifyNamed((t.name as Id).name, ifaceItems);
}
return unsupported("this type waits on the interop stages");
}
/** Classify a type by its declared name in the interface. */
function classifyNamed(name: String, ifaceItems: GrowableArray<InterfaceItem>): Ty {
for (let item in ifaceItems) {
if (item.tag != InterfaceItemTag.TypeDef) { continue; }
let td = item.typeDef as TypeDef;
if (td.name.name != name) { continue; }
if (td.tag == TypeDefTag.Alias) {
return classifyType(td.aliasType as Type, ifaceItems);
}
if (td.tag == TypeDefTag.Resource) {
let ty = new Ty(TyKind.ResourceH, "", pascalName(name));
ty.size = 4;
ty.align = 4;
ty.flats = 1;
ty.resourceName = name;
let qualified = exportedQualifiedOf(currentSpecifier);
if (qualified != "") {
// The program's own: its class comes from the entry, not
// from a synthesized module.
ty.isProgram = true;
noteProgramResource(ty.typeName, name, qualified);
return ty;
}
ty.ownedClass = rendersAsResourceClass(currentSpecifier);
noteNamedType(ty);
return ty;
}
if (td.tag == TypeDefTag.Enum) {
let cases = td.enumCases as GrowableArray<EnumCaseDef>;
let ty = new Ty(TyKind.Enumeration, "", pascalName(name));
ty.caseCount = cases.length;
ty.size = discSize(cases.length);
ty.align = ty.size;
ty.flats = 1;
noteNamedType(ty);
return ty;
}
if (td.tag == TypeDefTag.Flags) {
let flags = td.flags as GrowableArray<FlagDef>;
let ty = new Ty(TyKind.Flags, "", pascalName(name));
ty.caseCount = flags.length;
ty.size = if (flags.length <= 8) 1
else if (flags.length <= 16) 2 else 4;
ty.align = ty.size;
ty.flats = 1;
noteNamedType(ty);
return ty;
}
if (td.tag == TypeDefTag.Record) {
let ty = new Ty(TyKind.RecordT, "", pascalName(name));
for (let f in td.fields as GrowableArray<Field>) {
let child = classifyType(f.type, ifaceItems);
if (child.kind == TyKind.Unsupported) {
return child;
}
markInAggregate(child);
ty.children.push(child);
ty.childNames.push(camelName(f.name.name));
}
layoutRecord(ty);
noteNamedType(ty);
return ty;
}
if (td.tag == TypeDefTag.Variant) {
let ty = new Ty(TyKind.VariantT, "", pascalName(name));
let cases = td.cases as GrowableArray<Case>;
for (let c in cases) {
let payload = c.type;
let child = if (payload == null) voidTy()
else classifyType(payload as Type, ifaceItems);
if (child.kind == TyKind.Unsupported) {
return child;
}
markInAggregate(child);
ty.children.push(child);
// Prefixed with the variant's name: two variants in one
// interface may declare same-named cases, and sealed cases
// are module-level classes.
ty.childNames.push(pascalName(name) + pascalName(c.name.name));
}
layoutVariant(ty, cases.length);
noteNamedType(ty);
return ty;
}
break;
}
// Not declared here: a `use` may bring the name in from another
// interface, whose synthesized module then owns the declarations.
for (let item in ifaceItems) {
if (item.tag != InterfaceItemTag.Use) { continue; }
let use = item.use as Use;
for (let n in use.names) {
let asName = n.asName;
if (asName != null) {
if ((asName as Id).name == name) {
return unsupported(
"a renaming `use` waits on the interop stages");
}
continue;
}
if (n.name.name != name) { continue; }
return classifyUsed(use, name);
}
}
return unsupported(`the named type '${name}' waits on the interop stages`);
}
/**
* Classify a `use`d name in its source interface's context: the
* package switches for the hop (a bare `use foo` resolves against
* the interface's own package), and the specifier switches so named
* types minted inside record their sibling-module imports.
*/
function classifyUsed(use: Use, name: String): Ty {
let ast = currentAst;
let pkg = currentPackage;
if (ast == null || pkg == null) {
return unsupported("`use` resolution has no document context");
}
let from = use.from;
var ns = (pkg as PackageName).namespace.name;
var path = "";
if (from is IdUsePath) {
path = (pkg as PackageName).name.name + "/" +
((from as IdUsePath).id as Id).name;
} else {
let p = (from as PackageUsePath).packageId as PackageName;
ns = p.namespace.name;
path = `${p.name.name}/${((from as PackageUsePath).name as Id).name}`;
}
let target = findInterfaceOrNull(ast as Ast, ns, path);
if (target == null) {
return unsupported("`use` names '" + ns + ":" + path +
"', which this package's WIT does not declare");
}
let found = target as FoundInterface;
let savedPackage = currentPackage;
let savedSpecifier = currentSpecifier;
currentPackage = found.packageName;
currentSpecifier = `${ns}:${path}`;
let ty = classifyNamed(name, found.def.items);
currentPackage = savedPackage;
currentSpecifier = savedSpecifier;
return ty;
}
/**
* `wait-for` → `waitFor`: a WIT name as a Zena identifier
* (docs/design/component-model.md, Part 5's name mapping).
*
* TODO: consider moving this into a utilities package, and benchmark a
* linear character copy against this slicing — the output can be
* pre-allocated at `kebab.length`, since it only ever shrinks.
*/
function camelName(kebab: String): String {
var out = "";
var upper = false;
for (var i = 0; i < kebab.length; i += 1) {
let c = kebab.getByteAt(i);
if (c == 45) { // '-'
upper = true;
continue;
}
var piece = kebab.sliceBytes(i, i + 1);
if (upper) {
piece = piece.asciiUpperCase();
upper = false;
}
out = out + piece;
}
return out;
}
/** `error-code` → `ErrorCode`: a WIT type name as a Zena type name. */
function pascalName(kebab: String): String {
let camel = camelName(kebab);
if (camel.length == 0) {
return camel;
}
return camel.sliceBytes(0, 1).asciiUpperCase() +
camel.sliceBytes(1, camel.length);
}
/** One memory-lift helper owed to the module: `name(ptr) -> ty`. */
final class LiftEntry {
key: String;
name: String;
ty: Ty;
new(this.key, this.name, this.ty);
}
/** One future payload type the module moves: owed its per-type canon
* builtin declares and its lift/lower helpers. */
final class FutureEntry {
/** The payload's WIT text — the dedup key and the canon spelling. */
key: String;
/** This entry's suffix in generated names (`liftFuture0`). */
index: i32;
/** The FutureH that registered it. */
ty: Ty;
new(this.key, this.index, this.ty);
}
/** What one module's rendering pulled in, for its import lines. */
final class SynthUses {
var hasAsync = false;
/** Whether a plugin kind's `create` was written — pulls in `claimPlugin`. */
var plugin = false;
var fixedArray = false;
var array = false;
var error = false;
var option = false;
var result = false;
/** Whether a `stream<u8>` position rendered — pulls in `Stream`. */
var stream = false;
/** The `zena:wasi` names used, in first-use order. */
abi = new Array<String>();
/** The `zena:wasi` names used, in first-use order. */
componentStream = new Array<String>();
/** Enums lifted from discriminants, each owed a range-checked lift. */
enumLifts = new Array<Ty>();
/** Memory-lift helpers owed, discovered recursively; `emitted`
* tracks how many have been rendered so far. */
lifts = new Array<LiftEntry>();
var emittedLifts = 0;
/** Aggregate types lifted from flat core values — an export's
* parameters — each owed a helper taking the slots. */
flatLifts = new GrowableArray<LiftEntry>();
var emittedFlatLifts = 0;
/** Whether anything was staged through the arena — the wrapper then
* ends its call with `releaseStaged()`. */
var stagedAny = false;
/** Fresh-name counter for generated locals. */
var tmpCount = 0;
/** Whether any resource class rendered — pulls in Disposable and
* the module's handle symbol. */
var anyResource = false;
/** The handle spellings a `resource class` position used, each
* pulling in its `zena:core` name; `disown` is what hands an owned
* handle to the host, or marks a lifted one that sits in an
* aggregate as unmanaged. */
var ownHandle = false;
var borrowHandle = false;
var unmanagedHandle = false;
var disown = false;
/** Whether generated code parks on `awaitWaitable`. */
var awaitWaitable = false;
/** Whether a bare result arm rendered — pulls in the `witUnit`
* helper, the one spellable void value. */
var unit = false;
/** Future payload types moved, each owed declares and helpers. */
futures = new Array<FutureEntry>();
/** Typed stream element types moved — anything but `u8`, whose
* pumps live in `zena:wasi` — each owed declares and helpers. */
streams = new Array<FutureEntry>();
/** How many of `streams` have had their helpers emitted. */
var emittedStreams = 0;
/** Whether a typed stream rendered — pulls in `StreamWriter`. */
var streamWriter = false;
/** How many of `futures` have had their helpers emitted. */
var emittedFutures = 0;
/** Whether a lifted future rendered — pulls in `DeferredFuture`,
* since a lifted future's read starts on its first await. */
var deferred = false;
nextTmp(): i32 {
let n = this.tmpCount;
this.tmpCount += 1;
return n;
}
useAbi(name: String): void {
for (let existing in this.abi) {
if (existing == name) { return; }
}
this.abi.push(name);
}
useComponentStream(name: String): void {
for (let existing in this.componentStream) {
if (existing == name) { return; }
}
this.componentStream.push(name);
}
/** The generated-name suffix for `ty`'s stream element,
* registering the entry on first sight. */
streamIndexOf(ty: Ty): i32 {
for (let existing in this.streams) {
if (existing.key == ty.witText) { return existing.index; }
}
let index = this.streams.length;
this.streams.push(new FutureEntry(ty.witText, index, ty));
return index;
}
/** The generated-name suffix for `ty`'s future payload,
* registering the entry on first sight. */
futureIndexOf(ty: Ty): i32 {
for (let existing in this.futures) {
if (existing.key == ty.witText) { return existing.index; }
}
let index = this.futures.length;
this.futures.push(new FutureEntry(ty.witText, index, ty));
return index;
}
needEnumLift(ty: Ty): void {
for (let existing in this.enumLifts) {
if (existing.typeName == ty.typeName) { return; }
}
this.error = true;
this.enumLifts.push(ty);
}
/** The helper name for lifting `ty` from flat slots, registering it. */
flatLiftNameOf(ty: Ty): String {
let key = structuralKey(ty);
for (let existing in this.flatLifts) {
if (existing.key == key) { return existing.name; }
}
let name = if (ty.typeName != "") {
"liftFlat" + ty.typeName
} else {
"liftFlatVal" + i32ToString(this.flatLifts.length)
};
this.flatLifts.push(new LiftEntry(key, name, ty));
return name;
}
/** The helper name for lifting `ty` from memory, registering it. */
liftNameOf(ty: Ty): String {
let key = structuralKey(ty);
for (let existing in this.lifts) {
if (existing.key == key) { return existing.name; }
}
let name = if (ty.typeName != "") {
"lift" + ty.typeName
} else {
"liftVal" + i32ToString(this.lifts.length)
};
this.lifts.push(new LiftEntry(key, name, ty));
return name;
}
}
/** A structural key for lift-helper dedup. Named types key by name —
* one interface, one namespace — and anonymous ones by shape. */
function structuralKey(ty: Ty): String {
if (ty.typeName != "") {
return ty.typeName;
}
if (ty.kind == TyKind.Scalar) { return ty.scalar; }
if (ty.kind == TyKind.Str) { return "string"; }
if (ty.kind == TyKind.BytesList) { return "bytes"; }
if (ty.kind == TyKind.StreamH) {
return if (isTypedStream(ty)) `stream(${ty.witText})`
else "stream<u8>";
}
if (ty.kind == TyKind.FutureH) { return `future(${ty.witText})`; }
var key = if (ty.kind == TyKind.ListT) "list("
else if (ty.kind == TyKind.OptionT) "option("
else if (ty.kind == TyKind.ResultT) "result("
else "tuple(";
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { key = key + ","; }
key = key + structuralKey(ty.children[i]);
}
return key + ")";
}
/** The Zena spelling of a lifted `ty`, for signatures and fields. */
function zenaTypeOf(ty: Ty, uses: SynthUses): String {
if (ty.kind == TyKind.Scalar) { return ty.scalar; }
if (ty.kind == TyKind.Str) { return "String"; }
if (ty.kind == TyKind.BytesList) {
uses.fixedArray = true;
return "FixedArray<u8>";
}
if (ty.kind == TyKind.ListT) {
uses.array = true;
return `Array<${zenaTypeOf(ty.children[0], uses)}>`;
}
if (ty.kind == TyKind.OptionT) {
uses.option = true;
return `Option<${zenaTypeOf(ty.children[0], uses)}>`;
}
if (ty.kind == TyKind.TupleT) {
var out = "(";
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { out = out + ", "; }
out = out + zenaTypeOf(ty.children[i], uses);
}
return out + ")";
}
if (ty.kind == TyKind.StreamH) {
uses.stream = true;
return `Stream<${streamElementZenaType(ty, uses)}>`;
}
if (ty.kind == TyKind.FutureH) {
return `Future<${futurePayloadZenaType(ty.children[0], uses)}>`;
}
if (ty.kind == TyKind.ResourceH && ty.ownedClass) {
if (ty.isBorrow) {
uses.borrowHandle = true;
return `Borrow<${ty.typeName}>`;
}
if (ty.inAggregate) {
uses.unmanagedHandle = true;
return `Unmanaged<${ty.typeName}>`;
}
uses.ownHandle = true;
return `Own<${ty.typeName}>`;
}
// Enumeration, Flags, RecordT, VariantT — all named. ResultT never
// reaches here: top-level results are handled in renderFunc, and
// nested ones are refused before rendering.
return ty.typeName;
}
/**
* The Zena spelling of a future's payload. A `result` payload is a stored
* result (`storedResultType`), with `void` standing in for a bare arm;
* everything else spells as itself.
*/
function futurePayloadZenaType(payload: Ty, uses: SynthUses): String {
if (payload.kind == TyKind.ResultT) {
return storedResultType(payload, uses);
}
return zenaTypeOf(payload, uses);
}
/** A stored result's Zena type: `Result<T, E>`. */
function storedResultType(ty: Ty, uses: SynthUses): String {
uses.result = true;
return `Result<${zenaTypeOf(ty.children[0], uses)}, ${zenaTypeOf(ty.children[1], uses)}>`;
}
/** The expression for a stored ok result holding `value`. */
function okResultExpr(value: String): String {
return `(true, ${value})`;
}
/** The expression for a stored error result holding `value`. */
function errResultExpr(value: String): String {
return `(false, ${value})`;
}
/** A result arm's payload as a match arm binds it: `let ok3` and the
* name, or `_` and no name for a void arm. */
final class ArmBinding {
pattern: String;
name: String;
new(this.pattern, this.name);
}
/**
* The binding for one arm of a stored result being lowered. The match
* moves the payload out once, so an owner inside it reaches the host
* exactly once, where reading it through a cast on each use would be a
* use after move.
*/
function resultArmBinding(arm: Ty, prefix: String, uses: SynthUses) {
if (isVoid(arm)) {
return new ArmBinding("_", "");
}
let name = `${prefix}${uses.nextTmp()}`;
return new ArmBinding(`let ${name}`, name);
}
/** Whether `ty` (or anything inside it) cannot be lifted yet. */
function liftBlocker(ty: Ty, nested: boolean): String {
if (ty.kind == TyKind.Unsupported) {
return ty.reason;
}
if (ty.kind == TyKind.ResultT && nested) {
return "a nested result waits on the interop stages";
}
if (ty.kind == TyKind.FutureH) {
// The payload lifts inside the generated helper. A result payload
// is allowed — it lifts into a stored Result there — so only its arms are
// nested; the helper also *lowers* the payload when the future is
// lowered, so both directions must work.
let payload = ty.children[0];
if (payload.kind == TyKind.ResultT) {
for (let arm in payload.children) {
if (isVoid(arm)) { continue; }
let blocked = liftBlocker(arm, true);
if (blocked != "") { return blocked; }
let unlowerable = lowerBlocker(arm);
if (unlowerable != "") { return unlowerable; }
}
return "";
}
let blocked = liftBlocker(payload, true);
if (blocked != "") { return blocked; }
return lowerBlocker(payload);
}
for (let child in ty.children) {
if (isVoid(child)) { continue; }
let blocked = liftBlocker(child, true);
if (blocked != "") {
return blocked;
}
}
return "";
}
/** The abi load call for a discriminant or flags word of `size`. */
function discLoad(size: i32, ptrExpr: String, uses: SynthUses) {
if (size == 1) {
uses.useAbi("loadU8");
return `loadU8(${ptrExpr})`;
}
if (size == 2) {
uses.useAbi("loadU16");
return `loadU16(${ptrExpr})`;
}
uses.useAbi("loadI32");
return `loadI32(${ptrExpr})`;
}
/**
* The expression lifting `ty` from memory at `ptrExpr`. Simple types
* inline; aggregates call a helper this registers for emission.
*/
function liftExprOf(ty: Ty, ptrExpr: String, uses: SynthUses) {
if (ty.kind == TyKind.Scalar) {
let s = ty.scalar;
if (s == "boolean") {
uses.useAbi("loadU8");
return `(loadU8(${ptrExpr}) != 0)`;
}
if (s == "u8") {
uses.useAbi("loadU8");
return `(loadU8(${ptrExpr}) as u8)`;
}
if (s == "i8") {
uses.useAbi("loadS8");
return `(loadS8(${ptrExpr}) as i8)`;
}
if (s == "u16") {
uses.useAbi("loadU16");
return `(loadU16(${ptrExpr}) as u16)`;
}
if (s == "i16") {
uses.useAbi("loadS16");
return `(loadS16(${ptrExpr}) as i16)`;
}
if (s == "i32") {
uses.useAbi("loadI32");
return `loadI32(${ptrExpr})`;
}
if (s == "u32") {
uses.useAbi("loadI32");
return `(loadI32(${ptrExpr}) as u32)`;
}
if (s == "i64") {
uses.useAbi("loadI64");
return `loadI64(${ptrExpr})`;
}
if (s == "u64") {
uses.useAbi("loadI64");
return `(loadI64(${ptrExpr}) as u64)`;
}
if (s == "f32") {
uses.useAbi("loadF32");
return `loadF32(${ptrExpr})`;
}
uses.useAbi("loadF64");
return `loadF64(${ptrExpr})`;
}
if (ty.kind == TyKind.Str) {
uses.useAbi("liftStringAt");
return `liftStringAt(${ptrExpr})`;
}
if (ty.kind == TyKind.BytesList) {
uses.useAbi("liftBytesAt");
return `liftBytesAt(${ptrExpr})`;
}
if (ty.kind == TyKind.Enumeration) {
uses.needEnumLift(ty);
let loaded = discLoad(ty.size, ptrExpr, uses);
return `lift${ty.typeName}(${loaded})`;
}
if (ty.kind == TyKind.Flags) {
let loaded = discLoad(ty.size, ptrExpr, uses);
return `((${loaded} as u32) as ${ty.typeName})`;
}
if (ty.kind == TyKind.ResourceH) {
uses.useAbi("loadI32");
if (ty.isProgram) {
let helper = if (ty.isBorrow) "At" else "Take";
return `${camelName(ty.resourceName)}${helper}(loadI32(${ptrExpr}))`;
}
return liftedHandle(ty, `loadI32(${ptrExpr})`, uses);
}
if (ty.kind == TyKind.StreamH) {
uses.useAbi("loadI32");
return streamLiftCall(ty, `loadI32(${ptrExpr})`, uses);
}
if (ty.kind == TyKind.FutureH) {
uses.useAbi("loadI32");
let fid = `${uses.futureIndexOf(ty)}`;
return `liftFuture${fid}(loadI32(${ptrExpr}))`;
}
// RecordT, VariantT, OptionT, TupleT, ListT: a generated helper.
return `${uses.liftNameOf(ty)}(${ptrExpr})`;
}
/** `ptr` displaced by a field offset, elided when zero. */
function atOffset(offset: i32) {
return if (offset == 0) "ptr" else `ptr + ${offset}`;
}
// ============================================================================
// The lowering half: parameters into flat slots and staged memory
// ============================================================================
/** The core value type one scalar spelling flattens to. */
function coreOf(scalar: String) {
if (scalar == "u64" || scalar == "i64") { return "i64"; }
if (scalar == "f32") { return "f32"; }
if (scalar == "f64") { return "f64"; }
return "i32";
}
/** `value` cast to its core flat type, as source text. */
function castToCore(scalar: String, value: String) {
if (scalar == "boolean") {
return `(if (${value}) 1 else 0)`;
}
if (scalar == "i32" || scalar == "i64" || scalar == "f32" ||
scalar == "f64") {
return value;
}
if (scalar == "u64") {
return `(${value} as i64)`;
}
return `(${value} as i32)`;
}
/**
* The core value types `ty` flattens to, or null when a variant's
* payloads would join across core types — a joined slot then needs
* bit-casts the generated source cannot spell yet. Only the flat form
* cares: the same variant inside a list lowers through memory, where
* every case writes its own layout.
*/
function flatCoreSlots(ty: Ty): GrowableArray<String> | null {
let out = new Array<String>();
if (ty.kind == TyKind.Scalar) {
out.push(coreOf(ty.scalar));
return out;
}
if (ty.kind == TyKind.Enumeration || ty.kind == TyKind.Flags ||
ty.kind == TyKind.ResourceH || ty.kind == TyKind.StreamH ||
ty.kind == TyKind.FutureH) {
out.push("i32");
return out;
}
if (ty.kind == TyKind.Str || ty.kind == TyKind.BytesList ||
ty.kind == TyKind.ListT) {
out.push("i32");
out.push("i32");
return out;
}
if (ty.kind == TyKind.RecordT || ty.kind == TyKind.TupleT) {
for (let child in ty.children) {
let inner = flatCoreSlots(child);
if (inner == null) {
return null;
}
for (let slot in inner as GrowableArray<String>) {
out.push(slot);
}
}
return out;
}
// OptionT, ResultT, VariantT: a discriminant, then the slotwise
// join of the arms.
out.push("i32");
let joined = new Array<String>();
for (let child in ty.children) {
if (isVoid(child)) { continue; }
let inner = flatCoreSlots(child);
if (inner == null) {
return null;
}
let arm = inner as GrowableArray<String>;
for (var i = 0; i < arm.length; i += 1) {
if (i < joined.length) {
joined[i] = joinCore(joined[i], arm[i]);
} else {
joined.push(arm[i]);
}
}
}
for (let slot in joined) {
out.push(slot);
}
return out;
}
/**
* The canonical ABI's join of two arms' slot types: the same type is
* itself, an f32 beside an i32 is an i32 (the float travels as its
* bits), and anything else is an i64 — an i32 widened, an f64 as its
* bits, an f32 as its bits widened. `writeSlot` lowers into the join
* and `liftFlatExpr` reads back out of it, through the `zena:math`
* reinterpret intrinsics when a float is involved.
*/
function joinCore(a: String, b: String): String {
if (a == b) { return a; }
if ((a == "i32" && b == "f32") || (a == "f32" && b == "i32")) {
return "i32";
}
return "i64";
}
/** Whether any generated lowering or lift reinterpreted float bits,
* which pulls the `zena:math` intrinsics into the module. Reset per
* rendered module. */
var reinterpretUsed = false;
/** The `zena:math` import a module that reinterpreted bits needs. */
let reinterpretImport =
"import { i32_reinterpret_f32, i64_reinterpret_f64, " +
"f32_reinterpret_i32, f64_reinterpret_i64 } from 'zena:math';\n";
/** Whether `ty` (or anything inside it) cannot be lowered yet. */
/**
* A lifted handle as the program holds it: the handle class around the
* wire index. For a `resource class` that is an `Own<T>` fresh from its
* constructor, except inside an aggregate, where it is disowned: a list
* element or record field cannot carry an owner, and the program adopts
* the ones it keeps.
*/
function liftedHandle(ty: Ty, handleExpr: String, uses: SynthUses): String {
let fresh = `new ${ty.typeName}(${handleExpr})`;
if (ty.ownedClass && ty.inAggregate) {
uses.disown = true;
return `disown(${fresh})`;
}
return fresh;
}
/**
* The wire index of a handle being lowered. For a `resource class`, an
* own in a bare position is disowned first: the index transfers to the
* callee, the move ends the caller's binding, and a disowned wrapper is
* never implicitly released. A borrow, or an unmanaged handle out of an
* aggregate, is read as it is.
*/
function loweredHandle(ty: Ty, value: String, uses: SynthUses) {
uses.useAbi("rawHandle");
if (ty.ownedClass && !ty.isBorrow && !ty.inAggregate) {
uses.disown = true;
return `disown(${value}).[rawHandle]()`;
}
return `${value}.[rawHandle]()`;
}
function lowerBlocker(ty: Ty): String {
if (ty.kind == TyKind.Unsupported) {
return ty.reason;
}
if (ty.kind == TyKind.ResourceH && ty.isProgram && ty.isBorrow) {
return "a borrow of the program's own resource cannot be lowered " +
"yet: it would need a handle minted for the call and dropped " +
"after it";
}
if (ty.kind == TyKind.ResultT) {
return "a result parameter waits on the interop stages (the " +
"inline Result is return-position-only)";
}
if (ty.kind == TyKind.FutureH) {
// The generated helper moves the payload both ways; the lift
// blocker's future case checks both directions.
return liftBlocker(ty, true);
}
for (let child in ty.children) {
if (isVoid(child)) { continue; }
let blocked = lowerBlocker(child);
if (blocked != "") {
return blocked;
}
}
return "";
}
/** Whether lowering `ty` may stage arena buffers. */
function mayStage(ty: Ty): boolean {
if (ty.kind == TyKind.Str || ty.kind == TyKind.BytesList ||
ty.kind == TyKind.ListT) {
return true;
}
if (ty.kind == TyKind.FutureH) {
// The payload stages inside the generated pump's own arena range,
// not the wrapper's frame.
return false;
}
for (let child in ty.children) {
if (mayStage(child)) {
return true;
}
}
return false;
}
/** The abi store call for a value of `size` bytes at `ptrExpr`. */
function storeCall(size: i32, isFloat: boolean, ptrExpr: String,
value: String, uses: SynthUses) {
let name = if (isFloat) {
if (size == 4) "storeF32" else "storeF64"
} else if (size == 1) {
"storeU8"
} else if (size == 2) {
"storeU16"
} else if (size == 8) {
"storeI64"
} else {
"storeI32"
};
uses.useAbi(name);
return `${name}(${ptrExpr}, ${value})`;
}
/** `ptrExpr` displaced by `offset`, elided when zero. */
function displaced(ptrExpr: String, offset: i32) {
return if (offset == 0) ptrExpr
else `(${ptrExpr}) + ${offset}`;
}
/**
* Emit statements writing `value` (of type `ty`) into memory at
* `ptrExpr`, per the canonical layout — the element form a staged
* list buffer is filled with. Buffers staged along the way register
* with the arena; `releaseStaged()` after the call frees them all.
*/
function lowerMemStmts(ty: Ty, value: String, ptrExpr: String,
uses: SynthUses): ZenaTemplate {
if (ty.kind == TyKind.Scalar) {
let isFloat = ty.scalar == "f32" || ty.scalar == "f64";
let call = storeCall(ty.size, isFloat, ptrExpr,
castToCore(ty.scalar, value), uses);
return zena`
${call};
`;
}
if (ty.kind == TyKind.Enumeration) {
let call = storeCall(ty.size, false, ptrExpr,
`(${value} as i32)`, uses);
return zena`
${call};
`;
}
if (ty.kind == TyKind.Flags) {
let call = storeCall(ty.size, false, ptrExpr,
`((${value} as u32) as i32)`, uses);
return zena`
${call};
`;
}
if (ty.kind == TyKind.ResourceH && ty.isProgram) {
uses.useAbi("storeI32");
let prefix = camelName(ty.resourceName);
return zena`
storeI32(${ptrExpr}, ${prefix}New_raw(${prefix}Register(${value})));
`;
}
if (ty.kind == TyKind.ResourceH) {
uses.useAbi("storeI32");
if (ty.ownedClass) {
let handle = loweredHandle(ty, value, uses);
return zena`
storeI32(${ptrExpr}, ${handle});
`;
}
uses.useAbi("rawHandle");
if (!ty.isBorrow) {
uses.useAbi("markMoved");
return zena`
storeI32(${ptrExpr}, ${value}.[rawHandle]());
${value}.[markMoved]();
`;
}
return zena`
storeI32(${ptrExpr}, ${value}.[rawHandle]());
`;
}
if (ty.kind == TyKind.StreamH) {
uses.useAbi("storeI32");
let streamCall = streamLowerCall(ty, value, uses);
return zena`
storeI32(${ptrExpr}, ${streamCall});
`;
}
if (ty.kind == TyKind.FutureH) {
uses.useAbi("storeI32");
let fid = `${uses.futureIndexOf(ty)}`;
return zena`
storeI32(${ptrExpr}, lowerFuture${fid}(${value}));
`;
}
if (ty.kind == TyKind.ResultT) {
// Only reachable as a future payload: the value is a stored result,
// and it lowers as the canonical two-case variant.
storedResultType(ty, uses);
let payoff = payloadOffset(ty);
uses.useAbi("storeU8");
let okBinding = resultArmBinding(ty.children[0], "ok", uses);
let errBinding = resultArmBinding(ty.children[1], "err", uses);
let okStmts = growable<ZenaTemplate>([zena`storeU8(${ptrExpr}, 0);`]);
if (!isVoid(ty.children[0])) {
okStmts.push(lowerMemStmts(ty.children[0], okBinding.name,
displaced(ptrExpr, payoff), uses));
}
let errStmts = growable<ZenaTemplate>([zena`storeU8(${ptrExpr}, 1);`]);
if (!isVoid(ty.children[1])) {
errStmts.push(lowerMemStmts(ty.children[1], errBinding.name,
displaced(ptrExpr, payoff), uses));
}
let okPattern = okBinding.pattern;
let errPattern = errBinding.pattern;
return zena`
match (${value}) {
case (true, ${okPattern}): {
${okStmts}
}
case (false, ${errPattern}): {
${errStmts}
}
}
`;
}
if (ty.kind == TyKind.Str || ty.kind == TyKind.BytesList) {
let stage = if (ty.kind == TyKind.Str) "stageString"
else "stageByteList";
uses.useAbi(stage);
uses.stagedAny = true;
let ptr = `ptr${uses.nextTmp()}`;
let len = `len${uses.nextTmp()}`;
let displacedPtr = displaced(ptrExpr, 4);
uses.useAbi("storeI32");
return zena`
let (${ptr}, ${len}) = ${stage}(${value});
storeI32(${ptrExpr}, ${ptr});
storeI32(${displacedPtr}, ${len});
`;
}
if (ty.kind == TyKind.ListT) {
let element = ty.children[0];
uses.useAbi("stageBuffer");
uses.stagedAny = true;
uses.useAbi("storeI32");
let buffer = `buffer${uses.nextTmp()}`;
let length = `length${uses.nextTmp()}`;
let index = `index${uses.nextTmp()}`;
let elemSize = `${element.size}`;
let elemStmt = lowerMemStmts(element, `${value}[${index}]`,
`${buffer} + ${index} * ${elemSize}`, uses);
let displacedPtr = displaced(ptrExpr, 4);
return zena`
var ${buffer} = 0;
let ${length} = ${value}.length;
if (${length} > 0) {
${buffer} = stageBuffer(${length} * ${elemSize});
for (var ${index} = 0; ${index} < ${length}; ${index} += 1) {
${elemStmt}
}
}
storeI32(${ptrExpr}, ${buffer});
storeI32(${displacedPtr}, ${length});
`;
}
if (ty.kind == TyKind.RecordT) {
let offsets = fieldOffsets(ty);
let stmts = new Array<ZenaTemplate>();
for (var i = 0; i < ty.children.length; i += 1) {
stmts.push(lowerMemStmts(ty.children[i],
`${value}.${ty.childNames[i]}`,
displaced(ptrExpr, offsets[i]), uses));
}
return zena`
${stmts}
`;
}
if (ty.kind == TyKind.TupleT) {
let offsets = fieldOffsets(ty);
let t = `t${uses.nextTmp()}`;
var tupleVars = "";
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { tupleVars = `${tupleVars}, `; }
tupleVars = `${tupleVars}${t}v${i}`;
}
let stmts = new Array<ZenaTemplate>();
for (var i = 0; i < ty.children.length; i += 1) {
stmts.push(lowerMemStmts(ty.children[i],
`${t}v${i}`,
displaced(ptrExpr, offsets[i]), uses));
}
return zena`
let (${tupleVars}) = ${value};
${stmts}
`;
}
if (ty.kind == TyKind.OptionT) {
uses.option = true;
uses.useAbi("storeU8");
let payoff = payloadOffset(ty);
let bound = `o${uses.nextTmp()}`;
let innerStmt = lowerMemStmts(ty.children[0], bound,
displaced(ptrExpr, payoff), uses);
return zena`
if (let Some {value as ${bound}} = ${value}) {
storeU8(${ptrExpr}, 1);
${innerStmt}
} else {
storeU8(${ptrExpr}, 0);
}
`;
}
// VariantT: an if chain over the sealed cases, each storing the
// discriminant and its own payload layout.
let payoff = payloadOffset(ty);
let chainSb = new StringBuilder();
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { chainSb.append("} else "); }
chainSb.append(`if (${value} is ${ty.childNames[i]}) {\n`);
let call = storeCall(
discSize(ty.caseCount), false, ptrExpr, `${i}`, uses);
chainSb.append(` ${call};\n`);
if (!isVoid(ty.children[i])) {
let armStmt = lowerMemStmts(ty.children[i],
`(${value} as ${ty.childNames[i]}).value`,
displaced(ptrExpr, payoff), uses);
emit(chainSb, " ", armStmt);
chainSb.append("\n");
}
}
chainSb.append("}");
let chain = chainSb.toString();
return zena`
${chain}
`;
}
/**
* Stage a list value's element buffer: allocates `length * stride`
* arena bytes, fills each element through `lowerMemStmts`, and hands
* the buffer and count to `finish`. An empty list stages nothing and
* passes `(0, 0)` — the canonical empty form, and `stageBuffer(0)`
* would return an unowned sentinel.
*/
function emitListStaging(sb: StringBuilder, ty: Ty, value: String,
indent: String, uses: SynthUses,
finish: (buf: String, count: String) => void) {
let element = ty.children[0];
uses.useAbi("stageBuffer");
uses.stagedAny = true;
let buffer = `buffer${uses.nextTmp()}`;
let length = `length${uses.nextTmp()}`;
let index = `index${uses.nextTmp()}`;
let elemSize = `${element.size}`;
let body = lowerMemStmts(element, `${value}[${index}]`,
`${buffer} + ${index} * ${elemSize}`, uses);
emit(sb, indent, zena`
var ${buffer} = 0;
let ${length} = ${value}.length;
if (${length} > 0) {
${buffer} = stageBuffer(${length} * ${elemSize});
for (var ${index} = 0; ${index} < ${length}; ${index} += 1) {
${body}
}
}
`);
sb.append("\n");
finish(buffer, length);
}
/**
* Emit statements assigning `value`'s flattened form into the slot
* variables `slots[base..]`; returns the number of slots consumed.
* Unwritten slots keep their zero initializers, which is what an
* absent option payload or a shorter variant arm leaves behind.
*/
/**
* The core types of the slots `lowerFlatStmts` is filling, parallel to
* the slot names: a variant's arms share slots, and a slot two arms
* disagree on is the canonical join of their types (an i32 beside an
* i64 is an i64), so an arm's narrower value widens on the way in.
* Set by the caller that declared the slots.
*/
var currentSlotTypes = new Array<String>();
/**
* `slot = expr;`, widening an i32 `expr` when the slot is an i64 —
* the one join this file lowers (the canonical ABI also joins floats
* with integers, through reinterpretation, which waits on a need).
*/
function writeSlot(sb: StringBuilder, indent: String, slot: String,
slotIndex: i32, expr: String, haveCore: String) {
var rhs = expr;
if (slotIndex < currentSlotTypes.length) {
let want = currentSlotTypes[slotIndex];
if (want != haveCore) {
// Into a joined slot: an integer widens, a float goes as its
// bits (widened too, for an f32 in an i64).
if (want == "i64" && haveCore == "i32") {
rhs = `((${expr}) as i64)`;
} else if (want == "i32" && haveCore == "f32") {
reinterpretUsed = true;
rhs = `i32_reinterpret_f32(${expr})`;
} else if (want == "i64" && haveCore == "f32") {
reinterpretUsed = true;
rhs = `(i32_reinterpret_f32(${expr}) as i64)`;
} else if (want == "i64" && haveCore == "f64") {
reinterpretUsed = true;
rhs = `i64_reinterpret_f64(${expr})`;
}
}
}
sb.append(indent).append(`${slot} = ${rhs};\n`);
}
function lowerFlatStmts(sb: StringBuilder, ty: Ty, value: String,
slots: GrowableArray<String>, base: i32, indent: String,
uses: SynthUses): i32 {
if (ty.kind == TyKind.Scalar) {
writeSlot(sb, indent, slots[base], base, castToCore(ty.scalar, value),
coreOf(ty.scalar));
return 1;
}
if (ty.kind == TyKind.Enumeration) {
writeSlot(sb, indent, slots[base], base, `(${value} as i32)`,
"i32");
return 1;
}
if (ty.kind == TyKind.Flags) {
writeSlot(sb, indent, slots[base], base,
`((${value} as u32) as i32)`, "i32");
return 1;
}
if (ty.kind == TyKind.ResourceH && ty.isProgram) {
// An own of the program's resource leaves as a fresh handle over
// the instance's representation.
let prefix = camelName(ty.resourceName);
writeSlot(sb, indent, slots[base], base,
`${prefix}New_raw(${prefix}Register(${value}))`, "i32");
return 1;
}
if (ty.kind == TyKind.ResourceH) {
if (ty.ownedClass) {
writeSlot(sb, indent, slots[base], base,
loweredHandle(ty, value, uses), "i32");
return 1;
}
uses.useAbi("rawHandle");
writeSlot(sb, indent, slots[base], base, `${value}.[rawHandle]()`,
"i32");
if (!ty.isBorrow) {
// An owned handle transfers to the callee: the wrapper's later
// dispose must not drop an index it no longer owns.
uses.useAbi("markMoved");
sb.append(indent).append(`${value}.[markMoved]();\n`);
}
return 1;
}
if (ty.kind == TyKind.StreamH) {
writeSlot(sb, indent, slots[base], base,
streamLowerCall(ty, value, uses), "i32");
return 1;
}
if (ty.kind == TyKind.FutureH) {
writeSlot(sb, indent, slots[base], base,
`lowerFuture${uses.futureIndexOf(ty)}(${value})`, "i32");
return 1;
}
if (ty.kind == TyKind.Str || ty.kind == TyKind.BytesList) {
let stage = if (ty.kind == TyKind.Str) "stageString"
else "stageByteList";
uses.useAbi(stage);
uses.stagedAny = true;
let ptr = `ptr${uses.nextTmp()}`;
let len = `len${uses.nextTmp()}`;
sb.append(indent).append(`let (${ptr}, ${len}) = ${stage}(${value});\n`);
writeSlot(sb, indent, slots[base], base, ptr, "i32");
writeSlot(sb, indent, slots[base + 1], base + 1, len, "i32");
return 2;
}
if (ty.kind == TyKind.ListT) {
emitListStaging(sb, ty, value, indent, uses,
(buffer, length) => {
writeSlot(sb, indent, slots[base], base, buffer, "i32");
writeSlot(sb, indent, slots[base + 1], base + 1, length, "i32");
});
return 2;
}
if (ty.kind == TyKind.RecordT) {
var consumed = 0;
for (var i = 0; i < ty.children.length; i += 1) {
consumed += lowerFlatStmts(sb, ty.children[i],
`${value}.${ty.childNames[i]}`, slots, base + consumed,
indent, uses);
}
return consumed;
}
if (ty.kind == TyKind.TupleT) {
let t = `t${uses.nextTmp()}`;
sb.append(indent).append("let (");
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { sb.append(", "); }
sb.append(`${t}v${i}`);
}
sb.append(") = ").append(value).append(";\n");
var consumed = 0;
for (var i = 0; i < ty.children.length; i += 1) {
consumed += lowerFlatStmts(sb, ty.children[i],
`${t}v${i}`, slots, base + consumed, indent,
uses);
}
return consumed;
}
if (ty.kind == TyKind.OptionT) {
uses.option = true;
let bound = `o${uses.nextTmp()}`;
sb.append(indent).append(`if (let Some {value as ${bound}} = ${value}) {\n`);
writeSlot(sb, indent + " ", slots[base], base, "1", "i32");
lowerFlatStmts(sb, ty.children[0], bound,
slots, base + 1, indent + " ", uses);
sb.append(indent).append("}\n");
let total = flatCoreSlots(ty);
return (total as GrowableArray<String>).length;
}
if (ty.kind == TyKind.ResultT) {
// Only reachable as an async export's result: the value is a
// stored result, lowered as the canonical two-case variant.
storedResultType(ty, uses);
let okBinding = resultArmBinding(ty.children[0], "ok", uses);
let errBinding = resultArmBinding(ty.children[1], "err", uses);
let armIndent = indent + " ";
sb.append(indent).append(`match (${value}) {\n`);
sb.append(indent).append(` case (true, ${okBinding.pattern}): {\n`);
writeSlot(sb, armIndent, slots[base], base, "0", "i32");
if (!isVoid(ty.children[0])) {
lowerFlatStmts(sb, ty.children[0], okBinding.name,
slots, base + 1, armIndent, uses);
}
sb.append(indent).append(" }\n");
sb.append(indent).append(` case (false, ${errBinding.pattern}): {\n`);
writeSlot(sb, armIndent, slots[base], base, "1", "i32");
if (!isVoid(ty.children[1])) {
lowerFlatStmts(sb, ty.children[1], errBinding.name,
slots, base + 1, armIndent, uses);
}
sb.append(indent).append(" }\n");
sb.append(indent).append("}\n");
let total = flatCoreSlots(ty);
return (total as GrowableArray<String>).length;
}
// VariantT: an if chain; every arm writes the discriminant and its
// own prefix of the shared payload slots.
for (var i = 0; i < ty.children.length; i += 1) {
sb.append(indent);
if (i > 0) { sb.append("} else "); }
sb.append(`if (${value} is ${ty.childNames[i]}) {\n`);
writeSlot(sb, indent + " ", slots[base], base, `${i}`, "i32");
if (!isVoid(ty.children[i])) {
lowerFlatStmts(sb, ty.children[i],
`(${value} as ${ty.childNames[i]}).value`, slots,
base + 1, indent + " ", uses);
}
}
sb.append(indent).append("}\n");
let total = flatCoreSlots(ty);
return (total as GrowableArray<String>).length;
}
/** Emit the body of one registered lift helper. */
function emitLiftHelper(entry: LiftEntry, uses: SynthUses) {
let ty = entry.ty;
let retType = zenaTypeOf(ty, uses);
if (ty.kind == TyKind.RecordT) {
let offsets = fieldOffsets(ty);
var args = "";
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { args = `${args},\n`; }
args = `${args}${liftExprOf(ty.children[i], atOffset(offsets[i]), uses)}`;
}
return zena`
function ${entry.name}(ptr: i32): ${retType} {
return new ${ty.typeName}(
${args});
}
`;
}
if (ty.kind == TyKind.TupleT) {
let offsets = fieldOffsets(ty);
var args = "";
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { args = `${args},\n`; }
args = `${args}${liftExprOf(ty.children[i], atOffset(offsets[i]), uses)}`;
}
return zena`
function ${entry.name}(ptr: i32): ${retType} {
return (
${args});
}
`;
}
if (ty.kind == TyKind.OptionT) {
uses.option = true;
let payoff = payloadOffset(ty);
let disc = discLoad(1, "ptr", uses);
let inner = liftExprOf(ty.children[0], `ptr + ${payoff}`, uses);
return zena`
function ${entry.name}(ptr: i32): ${retType} {
if (${disc} == 0) {
return none;
}
return some(${inner});
}
`;
}
if (ty.kind == TyKind.VariantT) {
uses.error = true;
let payoff = payloadOffset(ty);
let disc = discLoad(discSize(ty.caseCount), "ptr", uses);
let casesSb = new StringBuilder();
for (var i = 0; i < ty.children.length; i += 1) {
casesSb.append(`if (disc == ${i}) {\n`);
if (isVoid(ty.children[i])) {
casesSb.append(` return new ${ty.childNames[i]}();\n}\n`);
} else {
let childExpr = liftExprOf(ty.children[i], `ptr + ${payoff}`, uses);
casesSb.append(` return new ${ty.childNames[i]}(${childExpr});\n}\n`);
}
}
let cases = casesSb.toString();
return zena`
function ${entry.name}(ptr: i32): ${retType} {
let disc = ${disc};
${cases}
throw new Error('invalid ${ty.typeName} discriminant');
}
`;
}
// ListT:
let element = ty.children[0];
let elemType = zenaTypeOf(element, uses);
let elemSize = `${element.size}`;
let elemExpr = liftExprOf(element, `base + i * ${elemSize}`, uses);
uses.useAbi("loadI32");
uses.useAbi("freeLifted");
uses.array = true;
return zena`
function ${entry.name}(ptr: i32): ${retType} {
return ${entry.name}Elems(loadI32(ptr), loadI32(ptr + 4));
}
function ${entry.name}Elems(base: i32, count: i32): ${retType} {
let out = new GrowableArray<${elemType}>();
for (var i = 0; i < count; i += 1) {
out.push(${elemExpr});
}
if (count > 0) {
freeLifted(base);
}
return out;
}
`;
}
// ============================================================================
// The flat lifting half: an export's parameters out of core values
// ============================================================================
/** A core value cast to its scalar spelling, as source text. */
function castFromCore(scalar: String, expr: String) {
if (scalar == "boolean") {
return `(${expr} != 0)`;
}
if (scalar == "i32" || scalar == "i64" || scalar == "f32" ||
scalar == "f64") {
return expr;
}
return `(${expr} as ${scalar})`;
}
/**
* The value of `ty` lifted from the flat core values `slots[base..]`,
* as one expression — the mirror of `lowerFlatStmts`. A slot whose
* core type is the join of several arms' (an i64 beside an i32) is
* narrowed back for the arm that wants the narrower one. Aggregates
* lift through a generated helper taking their slots.
*/
function liftFlatExpr(ty: Ty, slotTypes: GrowableArray<String>,
slots: GrowableArray<String>, base: i32, uses: SynthUses) {
let slot = (i: i32, want: String) => {
let have = slotTypes[i];
if (have == want) {
return slots[i];
}
// Out of a joined slot: an i64 wraps to an i32, and a float comes
// back from its bits.
if (have == "i64" && want == "i32") {
return `(${slots[i]} as i32)`;
}
if (have == "i32" && want == "f32") {
reinterpretUsed = true;
return `f32_reinterpret_i32(${slots[i]})`;
}
if (have == "i64" && want == "f32") {
reinterpretUsed = true;
return `f32_reinterpret_i32((${slots[i]} as i32))`;
}
if (have == "i64" && want == "f64") {
reinterpretUsed = true;
return `f64_reinterpret_i64(${slots[i]})`;
}
return slots[i];
};
if (ty.kind == TyKind.Scalar) {
return castFromCore(ty.scalar, slot(base, coreOf(ty.scalar)));
}
if (ty.kind == TyKind.Enumeration) {
uses.needEnumLift(ty);
return `lift${ty.typeName}(${slot(base, "i32")})`;
}
if (ty.kind == TyKind.Flags) {
return `((${slot(base, "i32")} as u32) as ${ty.typeName})`;
}
if (ty.kind == TyKind.ResourceH) {
if (ty.isProgram) {
// A borrow of the program's own resource arrives as its
// representation — the canonical ABI passes a borrow into the
// implementing component as the rep — so it is a table lookup.
// An own arrives as a handle the caller gave up: the instance
// is taken back out of the table.
let helper = if (ty.isBorrow) "At" else "Take";
return `${camelName(ty.resourceName)}${helper}(${slot(base, "i32")})`;
}
// An owned handle: the wrapper's class around it, which the
// program then owns and disposes. A borrow is refused before this.
return liftedHandle(ty, slot(base, "i32"), uses);
}
if (ty.kind == TyKind.StreamH) {
return streamLiftCall(ty, slot(base, "i32"), uses);
}
if (ty.kind == TyKind.FutureH) {
let fid = `${uses.futureIndexOf(ty)}`;
return `liftFuture${fid}(${slot(base, "i32")})`;
}
if (ty.kind == TyKind.Str) {
uses.useAbi("takeStringArgument");
return `takeStringArgument(${slot(base, "i32")}, ${slot(base + 1, "i32")})`;
}
if (ty.kind == TyKind.BytesList) {
uses.useAbi("takeBytesArgument");
return `takeBytesArgument(${slot(base, "i32")}, ${slot(base + 1, "i32")})`;
}
if (ty.kind == TyKind.ListT) {
return `${uses.liftNameOf(ty)}Elems(${slot(base, "i32")}, ${slot(base + 1, "i32")})`;
}
// RecordT, TupleT, OptionT, ResultT, VariantT: a generated helper
// taking the slots — at the aggregate's own slot types, which may
// be narrower than the joined ones it sits in.
let own = flatCoreSlots(ty) as GrowableArray<String>;
var args = "";
for (var i = 0; i < own.length; i += 1) {
if (i > 0) { args = `${args}, `; }
args = `${args}${slot(base + i, own[i])}`;
}
return `${uses.flatLiftNameOf(ty)}(${args})`;
}
/** Emit the body of one registered flat lift helper: the aggregate
* built from its flat core values, `s0..sN`. */
function emitFlatLiftHelper(entry: LiftEntry, uses: SynthUses) {
let ty = entry.ty;
let slotTypes = flatCoreSlots(ty) as GrowableArray<String>;
let slots = new GrowableArray<String>();
var params = "";
for (var i = 0; i < slotTypes.length; i += 1) {
let name = `s${i}`;
slots.push(name);
if (i > 0) { params = `${params}, `; }
params = `${params}${name}: ${slotTypes[i]}`;
}
let retType = futurePayloadZenaType(ty, uses);
if (ty.kind == TyKind.RecordT) {
var args = "";
var at = 0;
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { args = `${args},\n`; }
args = `${args}${liftFlatExpr(ty.children[i], slotTypes, slots, at, uses)}`;
at += (flatCoreSlots(ty.children[i]) as GrowableArray<String>).length;
}
return zena`
function ${entry.name}(${params}): ${retType} {
return new ${ty.typeName}(
${args});
}
`;
}
if (ty.kind == TyKind.TupleT) {
var args = "";
var at = 0;
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { args = `${args},\n`; }
args = `${args}${liftFlatExpr(ty.children[i], slotTypes, slots, at, uses)}`;
at += (flatCoreSlots(ty.children[i]) as GrowableArray<String>).length;
}
return zena`
function ${entry.name}(${params}): ${retType} {
return (
${args});
}
`;
}
if (ty.kind == TyKind.OptionT) {
uses.option = true;
let inner = liftFlatExpr(ty.children[0], slotTypes, slots, 1, uses);
return zena`
function ${entry.name}(${params}): ${retType} {
if (s0 == 0) {
return none;
}
return some(${inner});
}
`;
}
if (ty.kind == TyKind.ResultT) {
storedResultType(ty, uses);
let okZ = futurePayloadZenaType(ty.children[0], uses);
let errZ = futurePayloadZenaType(ty.children[1], uses);
let arm = (child: Ty) => {
if (isVoid(child)) {
uses.unit = true;
return "witUnit()";
}
return liftFlatExpr(child, slotTypes, slots, 1, uses);
};
let okArm = arm(ty.children[0]);
let errArm = arm(ty.children[1]);
return zena`
function ${entry.name}(${params}): ${retType} {
if (s0 == 0) {
return ${okResultExpr(okArm)};
}
return ${errResultExpr(errArm)};
}
`;
}
// VariantT: the discriminant picks the case, each reading its own
// prefix of the shared payload slots.
uses.error = true;
let casesSb = new StringBuilder();
for (var i = 0; i < ty.children.length; i += 1) {
casesSb.append(`if (s0 == ${i}) {\n`);
if (isVoid(ty.children[i])) {
casesSb.append(` return new ${ty.childNames[i]}();\n}\n`);
} else {
let childExpr = liftFlatExpr(ty.children[i], slotTypes, slots, 1, uses);
casesSb.append(` return new ${ty.childNames[i]}(${childExpr});\n}\n`);
}
}
let cases = casesSb.toString();
return zena`
function ${entry.name}(${params}): ${retType} {
${cases}
throw new Error('invalid ${ty.typeName} discriminant');
}
`;
}
/** The `zena:stream` import a module that rendered streams needs. */
function streamImport(uses: SynthUses) {
return if (uses.streamWriter) "import { Stream, StreamWriter } from 'zena:stream';\n"
else "import { Stream } from 'zena:stream';\n";
}
/** Whether `ty` is or contains a stream or future end. */
function carriesEnd(ty: Ty): boolean {
if (ty.kind == TyKind.StreamH || ty.kind == TyKind.FutureH) {
return true;
}
for (let child in ty.children) {
if (carriesEnd(child)) { return true; }
}
return false;
}
/**
* Whether a value of `ty` holds an owner: an owned handle of a
* `resource class` in a bare position, or a tuple, option, result,
* future or stream holding one. Such a value is affine, so a container
* of it is a restricted instantiation (owner-futures.md): one element
* at a time through a stream, and nothing in a `GrowableArray`.
*/
function holdsOwner(ty: Ty): boolean {
if (ty.kind == TyKind.ResourceH) {
return ty.ownedClass && !ty.isBorrow && !ty.inAggregate;
}
for (let child in ty.children) {
if (holdsOwner(child)) { return true; }
}
return false;
}
/** Whether a stream position carries an element other than `u8`,
* moved by generated pumps rather than `zena:wasi`'s byte pumps. */
function isTypedStream(ty: Ty): boolean {
return ty.children.length > 0;
}
/** The Zena spelling of a stream's element. */
function streamElementZenaType(ty: Ty, uses: SynthUses): String {
return if (isTypedStream(ty)) zenaTypeOf(ty.children[0], uses) else "u8";
}
/** The expression lifting a stream handle into a `Stream<T>`. */
function streamLiftCall(ty: Ty, handle: String, uses: SynthUses): String {
if (isTypedStream(ty)) {
let sid = `${uses.streamIndexOf(ty)}`;
return `liftStream${sid}(${handle})`;
}
uses.useComponentStream("liftByteStream");
return `liftByteStream(${handle})`;
}
/** The expression lowering a `Stream<T>` into a stream handle. */
function streamLowerCall(ty: Ty, value: String, uses: SynthUses): String {
if (isTypedStream(ty)) {
let sid = `${uses.streamIndexOf(ty)}`;
return `lowerStream${sid}(${value})`;
}
uses.useComponentStream("lowerByteStream");
return `lowerByteStream(${value})`;
}
/** Elements a typed inbound pump reads per canonical copy. */
let STREAM_CHUNK = 64;
/**
* One typed stream element's generated surface: the five per-type
* canon builtin declares (`#k`-disambiguated like a future's, the
* canon type spelled `stream:<iface>#<element>`), the lift helper
* that reads a received end into a `Stream<T>` through a
* `StreamWriter`, and the lower helper that makes a fresh pair, hands
* over the readable end and pumps the guest stream's elements into
* the writable one. Each element crosses through memory at its
* canonical layout — the read pump lifts a chunk of them out of a
* return area, the write pump lowers one at a time into a staged
* buffer — so a string or list inside an element is fine. Bytes keep
* `zena:wasi`'s chunked pumps, which never marshal.
*/
function emitStreamHelpers(sb: StringBuilder, entry: FutureEntry,
interfaceName: String, uses: SynthUses) {
let k = `${entry.index}`;
let element = entry.ty.children[0];
let canonType = `stream:${interfaceName}#${entry.ty.witText}`;
let z = zenaTypeOf(element, uses);
uses.awaitWaitable = true;
uses.error = true;
uses.option = true;
uses.stream = true;
uses.streamWriter = true;
uses.fixedArray = true;
uses.useAbi("resultArea");
uses.useAbi("freeLifted");
uses.useAbi("stagedMark");
uses.useAbi("releaseStagedFrom");
uses.useAbi("stageBuffer");
let declare = (builtin: String, options: String, name: String,
sig: String) => {
sb.append(`@external("canon", "${builtin}#${interfaceName}.${k}", "${canonType}${options}")\n`);
sb.append(`declare function ${name}${k}_raw${sig};\n`);
};
declare("stream.new", "", "streamNew", "(): u64");
declare("stream.read", ",async", "streamRead",
"(end: i32, ptr: i32, count: i32): i32");
declare("stream.write", ",async", "streamWrite",
"(end: i32, ptr: i32, count: i32): i32");
declare("stream.drop-readable", "", "streamDropReadable",
"(end: i32): void");
declare("stream.drop-writable", "", "streamDropWritable",
"(end: i32): void");
let size = `${element.size}`;
let chunkSize = `${STREAM_CHUNK}`;
let elemExpr = liftExprOf(element, `buf + i * ${size}`, uses);
let lowerElemStmt = lowerMemStmts(element, "v", "buf", uses);
// A write the reader refused took nothing, and lowering the element
// already moved its handles out of their classes into the buffer,
// where they are still this component's: lift them back, and the
// binding releases them where it ends (#833).
let reclaim = if (holdsOwner(element)) zena`
if ((packed >> 4) == 0) {
let refused = ${liftExprOf(element, "buf", uses)};
}
` else "";
// A chunk of plain elements goes to the reader in one bulk write. A
// stream of owners is one element at a time (only a first-class
// stream has the bulk path), and every element read is the
// program's from then on: the one a stopped reader hands back, and
// the rest of the chunk after it, are released here.
let deliver = if (holdsOwner(element)) zena`
for (var i = 0; i < n; i += 1) {
let item = ${elemExpr};
if (open) {
if (let (false, refused) = await writer.write(item)) {
open = false;
}
}
}
` else zena`
let items = new GrowableArray<${z}>(n);
for (var i = 0; i < n; i += 1) {
items.push(${elemExpr});
}
let delivered = await writer.writeAll(FixedArray.from(items), n);
if (!delivered) {
open = false;
}
`;
emit(sb, "", zena`
function liftStream${k}(end: i32): Stream<${z}> {
let (writer, stream) = StreamWriter.create<${z}>();
pumpStreamIn${k}(end, writer);
return stream;
}
async function pumpStreamIn${k}(end: i32, writer: StreamWriter<${z}>): Future<void> {
let buf = resultArea(${chunkSize} * ${size});
var open = true;
while (open) {
var packed = streamRead${k}_raw(end, buf, ${chunkSize});
if (packed == -1) {
packed = await awaitWaitable(end);
}
let n = packed >> 4;
let completed = (packed & 15) == 0;
if (n > 0) {
${deliver}
} else if (completed) {
freeLifted(buf);
throw new Error('the stream read made no progress');
}
if (!completed) {
open = false;
}
}
freeLifted(buf);
writer.close();
streamDropReadable${k}_raw(end);
}
function lowerStream${k}(source: Stream<${z}>): i32 {
let pair = streamNew${k}_raw();
pumpStreamOut${k}(source, (pair >> 32) as i32);
return pair as i32;
}
async function pumpStreamOut${k}(source: Stream<${z}>, end: i32): Future<void> {
var open = true;
while (open) {
if (let Some {value as v} = await source.readOne()) {
let m0 = stagedMark();
let buf = stageBuffer(${size});
${lowerElemStmt}
var packed = streamWrite${k}_raw(end, buf, 1);
if (packed == -1) {
packed = await awaitWaitable(end);
}
${reclaim}
releaseStagedFrom(m0);
if ((packed & 15) != 0) {
source.stop();
open = false;
}
} else {
open = false;
}
}
streamDropWritable${k}_raw(end);
}
`);
sb.append("\n");
}
/**
* One future payload type's generated surface: the five per-type
* canon builtin declares (each field disambiguated `#<interface>.<k>`,
* because the canon entry's type is part of which builtin it is, every
* declaration is its own core import, and two interfaces' `k`s both
* start at 0), the lift helper that reads a
* received end into a `Future`, and the lower helper that makes a
* fresh pair, hands over the readable end and pumps the guest future
* into the writable one. A `result` payload is a stored `Result`,
* with `witUnit()` filling a bare arm.
*/
function emitFutureHelpers(sb: StringBuilder, entry: FutureEntry,
interfaceName: String, uses: SynthUses) {
let k = `${entry.index}`;
let payload = entry.ty.children[0];
let canonType = `future:${interfaceName}#${entry.ty.witText}`;
let z = futurePayloadZenaType(payload, uses);
uses.awaitWaitable = true;
uses.error = true;
uses.useAbi("resultArea");
uses.useAbi("freeLifted");
uses.useAbi("stagedMark");
uses.useAbi("releaseStagedFrom");
uses.useAbi("stageBuffer");
let declare = (builtin: String, options: String, name: String,
sig: String) => {
sb.append(`@external("canon", "${builtin}#${interfaceName}.${k}", "${canonType}${options}")\n`);
sb.append(`declare function ${name}${k}_raw${sig};\n`);
};
declare("future.new", "", "futureNew", "(): u64");
declare("future.read", ",async", "futureRead",
"(end: i32, ptr: i32): i32");
declare("future.write", ",async", "futureWrite",
"(end: i32, ptr: i32): i32");
declare("future.drop-readable", "", "futureDropReadable",
"(end: i32): void");
declare("future.drop-writable", "", "futureDropWritable",
"(end: i32): void");
// The lift: a `DeferredFuture`, whose read starts on the first
// await. A read issued at lift time holds a waitable — and the task
// that owns it — until the host writes the end, and a program need
// not ever look: every `request.new` and `response.new` returns a
// `transmitted` future beside the resource (#587). The read, once
// started: one canonical read, parked on the driver when BLOCKED
// (-1); the low CopyResult bits are 0 (COMPLETED) exactly when a
// value arrived, and a peer that dropped its end without writing
// fails the future with a throw.
uses.deferred = true;
let payloadSize = `${payload.size}`;
var readPayload = zena``;
if (payload.kind == TyKind.ResultT) {
let okZ = zenaTypeOf(payload.children[0], uses);
let errZ = zenaTypeOf(payload.children[1], uses);
let payoff = `${payloadOffset(payload)}`;
var okExpr = "ok";
var errExpr = "err";
if (isVoid(payload.children[0])) {
uses.unit = true;
okExpr = "witUnit()";
}
if (isVoid(payload.children[1])) {
uses.unit = true;
errExpr = "witUnit()";
}
let disc = discLoad(1, "ret", uses);
storedResultType(payload, uses);
let okValue = okResultExpr(okExpr);
let errValue = errResultExpr(errExpr);
var okArm = zena`
freeLifted(ret);
return ${okValue};
`;
if (okExpr == "ok") {
okArm = zena`
let ok = ${liftExprOf(payload.children[0], `ret + ${payoff}`, uses)};
freeLifted(ret);
return ${okValue};
`;
}
var errArm = zena`
freeLifted(ret);
return ${errValue};
`;
if (errExpr == "err") {
errArm = zena`
let err = ${liftExprOf(payload.children[1], `ret + ${payoff}`, uses)};
freeLifted(ret);
return ${errValue};
`;
}
readPayload = zena`
if (${disc} == 0) {
${okArm}
}
${errArm}
`;
} else {
let out = liftExprOf(payload, "ret", uses);
readPayload = zena`
let out = ${out};
freeLifted(ret);
return out;
`;
}
let lowerPayloadStmt = lowerMemStmts(payload, "v", "buf", uses);
emit(sb, "", zena`
function liftFuture${k}(end: i32): Future<${z}> {
return new DeferredFuture<${z}>((): Future<${z}> => readFuture${k}(end), (): void => { futureDropReadable${k}_raw(end); });
}
async function readFuture${k}(end: i32): Future<${z}> {
let ret = resultArea(${payloadSize});
var packed = futureRead${k}_raw(end, ret);
if (packed == -1) {
packed = await awaitWaitable(end);
}
futureDropReadable${k}_raw(end);
if ((packed & 15) != 0) {
freeLifted(ret);
throw new Error('the future was dropped without a value');
}
${readPayload}
}
function lowerFuture${k}(value: Future<${z}>): i32 {
let pair = futureNew${k}_raw();
pumpFuture${k}(value, (pair >> 32) as i32);
return pair as i32;
}
async function pumpFuture${k}(value: Future<${z}>, end: i32): Future<void> {
let v = await value;
let m0 = stagedMark();
let buf = stageBuffer(${payloadSize});
${lowerPayloadStmt}
var packed = futureWrite${k}_raw(end, buf);
if (packed == -1) {
packed = await awaitWaitable(end);
}
releaseStagedFrom(m0);
futureDropWritable${k}_raw(end);
}
`);
sb.append("\n");
}
/**
* A WIT `enum`, as a Zena enum: PascalCase members with explicit
* ordinals, because the ordinal IS the wire discriminant and must not
* drift from declaration order by accident.
*/
function renderEnum(sb: StringBuilder, td: TypeDef) {
let cases = td.enumCases as GrowableArray<EnumCaseDef>;
let name = td.name.name;
let enumName = pascalName(name);
let comment = `/** WIT \`enum ${name}\`. */`;
let members = new GrowableArray<String>();
for (var i = 0; i < cases.length; i += 1) {
members.push(`${pascalName(cases[i].name.name)} = ${i},`);
}
emit(sb, "", zena`
${comment}
export enum ${enumName} {
${members}
}
`);
sb.append("\n");
}
/**
* A WIT `flags`, as a distinct u32 bitset with one constant per label
* (`modes` with `read` → `modesRead`). Distinct rather than opaque:
* combining flags is the caller's arithmetic, through `u32` casts.
*/
function renderFlags(sb: StringBuilder, td: TypeDef) {
let flags = td.flags as GrowableArray<FlagDef>;
let typeName = pascalName(td.name.name);
let prefix = camelName(td.name.name);
let name = td.name.name;
let comment = `/** WIT \`flags ${name}\`, as a bitset. */`;
let members = new GrowableArray<String>();
for (var i = 0; i < flags.length; i += 1) {
let flagName = pascalName(flags[i].name.name);
let val = `${1 << i}`;
members.push(`export let ${prefix}${flagName} = (${val} as u32) as ${typeName};`);
}
emit(sb, "", zena`
${comment}
export distinct type ${typeName} = u32;
${members}
`);
sb.append("\n");
}
/**
* A WIT `resource`, as a handle-wrapping class: the class owns the
* imported handle, methods and statics ride the same marshaling
* machinery as free functions (a method's raw call leads with the
* handle), a WIT constructor becomes `static create`, and disposal is
* the canonical `resource.drop`. For an interface in
* `ownedResourceSpecifiers` the class is a `resource class`, released
* by implicit drop and checked for use after a move; for the rest it
* is a `Disposable` whose dispose is idempotent behind a flag, because
* nothing prevents a double call there. Members that cannot render yet
* are skipped
* per member; the class itself always renders, so a handle received
* from elsewhere is at least holdable and droppable.
*/
function renderResource(
body: StringBuilder,
skipped: StringBuilder,
td: TypeDef,
interfaceName: String,
ifaceItems: GrowableArray<InterfaceItem>,
uses: SynthUses
) {
uses.anyResource = true;
// The symbol-keyed members: shared identities from the abi module,
// so another synthesized module's marshaling reaches the same
// members (a per-module symbol would not). A resource class has no
// moved flag, so only the Disposable form declares `[markMoved]`.
uses.useAbi("rawHandle");
let ownedClass = rendersAsResourceClass(selfSpecifier);
if (!ownedClass) {
uses.useAbi("markMoved");
}
let resourceName = td.name.name;
let typeName = pascalName(resourceName);
let rawPrefix = camelName(resourceName);
let members = new StringBuilder();
let raws = new StringBuilder();
let funcs = td.resourceFuncs;
if (funcs != null) {
for (let rf in funcs as GrowableArray<ResourceFunc>) {
var mode = new FnMode("", "", "", "", false);
var label = "";
if (rf.tag == ResourceFuncTag.Constructor) {
mode = new FnMode("[constructor]" + resourceName, "create",
rawPrefix + "Create", "static ", false, resourceName);
label = resourceName + " constructor";
} else if (rf.tag == ResourceFuncTag.Static) {
let fnName = rf.func.name.name;
mode = new FnMode(`[static]${resourceName}.${fnName}`,
zenaMemberName(fnName), rawPrefix + pascalName(fnName),
"static ", false);
label = `${resourceName}.${fnName}`;
} else {
let fnName = rf.func.name.name;
mode = new FnMode(`[method]${resourceName}.${fnName}`,
zenaMemberName(fnName), rawPrefix + pascalName(fnName), "",
true);
label = `${resourceName}.${fnName}`;
}
let reason = renderFuncIn(members, raws, rf.func, interfaceName,
ifaceItems, uses, mode);
if (reason != "") {
skipped.append("// ").append(label).append(": ")
.append(reason).append("\n");
}
}
}
let comment = `/** WIT \`resource ${resourceName}\`. */`;
if (ownedClass) {
// A `resource class`: the program holds it as `Own<T>`, implicit
// drop releases it at scope exit, a move ends the binding, and the
// checker reports a use after the move. Dispose consumes the
// receiver and drops the handle; there is no moved flag, because
// lowering an own disowns the wrapper instead. Each declaration of
// the drop is its own core import, named apart by the suffix, as
// the stream and future families are.
uses.ownHandle = true;
let canonType = `resource:${interfaceName}#${resourceName}`;
emit(body, "", zena`
${comment}
export resource class ${typeName} {
#handle: i32;
new(handle: i32) : #handle = handle;
/** The wire handle, module-internal. */
[rawHandle](): i32 {
return this.#handle;
}
[Disposable.dispose](this: Own<this>): void {
${rawPrefix}Drop_raw(this.#handle);
}
${members.toString()}
}
@external("canon", "resource.drop#${interfaceName}#${resourceName}", "${canonType}")
declare function ${rawPrefix}Drop_raw(handle: i32): void;
${raws.toString()}
`);
return;
}
body.append(comment).append("\n");
body.append("export final class ").append(typeName)
.append(" implements Disposable {\n");
body.append(" #handle: i32;\n");
body.append(" var #dropped = false;\n");
body.append(" new(handle: i32) : #handle = handle;\n\n");
body.append(" /** The wire handle, module-internal. */\n");
body.append(" [rawHandle](): i32 {\n return this.#handle;\n");
body.append(" }\n\n");
body.append(" /** The handle transferred to the host (an own\n");
body.append(" * parameter consumed it): dispose becomes a no-op,\n");
body.append(" * because the callee owns the drop now. Until affine\n");
body.append(" * checking covers these wrappers, a *use* after the\n");
body.append(" * move is a runtime trap rather than a compile\n");
body.append(" * error. */\n");
body.append(" [markMoved](): void {\n");
body.append(" this.#dropped = true;\n }\n\n");
body.append(" [Disposable.dispose](): void {\n");
body.append(" if (!this.#dropped) {\n");
body.append(" this.#dropped = true;\n");
body.append(" ").append(rawPrefix).append("Drop_raw(this.#handle);\n");
body.append(" }\n }\n\n");
body.append(members.toString());
body.append("}\n");
// Per resource: each declaration is its own core import, named
// apart by the suffix, as the stream and future families are.
body.append("@external(\"canon\", \"resource.drop#")
.append(interfaceName).append("#").append(resourceName)
.append("\", \"resource:")
.append(interfaceName).append("#").append(resourceName)
.append("\")\n");
body.append("declare function ").append(rawPrefix)
.append("Drop_raw(handle: i32): void;\n");
body.append(raws.toString());
}
/** A WIT `record`, as a case class. */
function renderRecord(sb: StringBuilder, td: TypeDef,
ifaceItems: GrowableArray<InterfaceItem>, uses: SynthUses) {
let ty = classifyNamed(td.name.name, ifaceItems);
let blocked = liftBlocker(ty, false);
if (blocked != "") {
return blocked;
}
let comment = `/** WIT \`record ${td.name.name}\`. */`;
var fields = "";
for (var i = 0; i < ty.children.length; i += 1) {
if (i > 0) { fields = `${fields}, `; }
fields = `${fields}${ty.childNames[i]}: ${zenaTypeOf(ty.children[i], uses)}`;
}
emit(sb, "", zena`
${comment}
export class ${ty.typeName}(${fields})
`);
sb.append("\n");
return "";
}
/** A WIT `variant`, as a sealed case-class hierarchy. */
function renderVariant(sb: StringBuilder, td: TypeDef,
ifaceItems: GrowableArray<InterfaceItem>, uses: SynthUses) {
let ty = classifyNamed(td.name.name, ifaceItems);
let blocked = liftBlocker(ty, false);
if (blocked != "") {
return blocked;
}
let comment = `/** WIT \`variant ${td.name.name}\`. */`;
let cases = new GrowableArray<String>();
for (var i = 0; i < ty.children.length; i += 1) {
let payload = if (!isVoid(ty.children[i])) {
`(value: ${zenaTypeOf(ty.children[i], uses)})`
} else {
""
};
cases.push(`case ${ty.childNames[i]}${payload}`);
}
emit(sb, "", zena`
${comment}
export sealed class ${ty.typeName} {
${cases}
}
`);
sb.append("\n");
return "";
}
/**
* The namespaces the WIT document declares packages under — its own
* and each nested `package ns:name { ... }` — each once. A program
* compiled against a declared world imports the world's interfaces
* by name, `ns:name/iface`, and the resolver maps a specifier's
* namespace to a package; these are the namespaces the document
* itself answers for.
*/
export function declaredPackageNamespaces(witSource: String): GrowableArray<String> {
// Syntax only: the world's `use` paths reach packages the compiler
// splices in later, and the package names need no resolution.
let ast = parseSyntax(witSource);
let names = new Array<String>();
let add = (pkg: PackageName | null) => {
if (pkg == null) { return; }
let ns = (pkg as PackageName).namespace.name;
for (let known in names) {
if (known == ns) { return; }
}
names.push(ns);
};
add(ast.packageName);
for (let nested in ast.nestedPackages) {
add(nested.name);
}
return names;
}
/** Where the root ends in a `wit:<root>#<spec>` canonical path: its `#`. */
function witRootEnd(canonicalPath: String) {
var hash = -1;
for (var i = 4; i < canonicalPath.length; i += 1) {
if (canonicalPath.getByteAt(i) == 35) { // '#'
hash = i;
}
}
if (hash < 0) {
throw new Error("Malformed WIT module path: " + canonicalPath);
}
return hash;
}
/**
* The WIT root a `wit:<root>#<ns>:<iface-path>` canonical path names:
* the file or directory whose document its module is synthesized from.
*/
function witRootOf(canonicalPath: String) {
return canonicalPath.sliceBytes(4, witRootEnd(canonicalPath));
}
var memoWasiDir = "";
var memoWasiWit = "";
async function readWasiWit(host: CompilerHost, witDir: String): Future<String> {
if (memoWasiDir == witDir && memoWasiWit != "") {
return memoWasiWit;
}
let source = await readWitSource(host, witDir);
memoWasiDir = witDir;
memoWasiWit = source;
return source;
}
/**
* The synthesized Zena source for a `wit:<root>#<ns>:<iface-path>`
* canonical path, its root's document read through `host`.
* `packagesWit` is the program's WIT-backed packages' source, spliced
* in where the root's document lacks it: a declared world's document
* is a root too, and its worlds import `wasi:cli` by name, which the
* parser resolves.
*/
export async function synthesizeWitModule(host: CompilerHost, canonicalPath: String,
packagesWit: String = ""): Future<String> {
let spec = canonicalPath.sliceBytes(witRootEnd(canonicalPath) + 1,
canonicalPath.length);
var colon = -1;
for (var i = 0; i < spec.length; i += 1) {
if (spec.getByteAt(i) == 58) { // ':'
colon = i;
break;
}
}
let namespace = spec.sliceBytes(0, colon);
let interfacePath = spec.sliceBytes(colon + 1, spec.length);
var allPackages = packagesWit;
let root = witRootOf(canonicalPath);
if (root == "host-wit" || root.endsWith("/host-wit")) {
if (!allPackages.contains("wasi:http@0.3.0")) {
let prefix = if (root == "host-wit") "" else root.sliceBytes(0, root.length - 8);
let witDir = if (prefix == "") "wit" else prefix + "wit";
try {
let wasiWit = await readWasiWit(host, witDir);
allPackages = if (allPackages == "") wasiWit else `${allPackages}\n${wasiWit}`;
} catch (e) {
// Leave allPackages as is if wit directory cannot be read
}
}
}
// The splice appends, so the spans the type text is read from hold.
// Every read is above this line: what follows writes the module-level
// state the synthesis reads, and runs without suspending.
let witSource = withWasiPackages(
await readWitSource(host, root), allPackages);
reinterpretUsed = false;
currentWitSource = witSource;
let ast = parsedWit(witSource);
let iface = findInterface(ast, namespace, interfacePath);
currentAst = ast;
currentPackage = iface.packageName;
selfSpecifier = `${namespace}:${interfacePath}`;
currentSpecifier = selfSpecifier;
usedTypeImports = new Array<UsedTypeImport>();
exportedInterfaces = new Array<ExportedInterface>();
programResources = new Array<ProgramResource>();
let version = iface.packageName.version;
var interfaceName = `${namespace}:${interfacePath}`;
if (version != null) {
interfaceName = `${interfaceName}@${version as String}`;
}
let sb = new StringBuilder();
sb.append("// Synthesized from WIT: ").append(interfaceName)
.append(". Do not edit.\n");
let body = new StringBuilder();
let skipped = new StringBuilder();
let uses = new SynthUses();
for (let item in iface.def.items) {
if (item.tag != InterfaceItemTag.Func) {
if (item.tag == InterfaceItemTag.TypeDef) {
let td = item.typeDef as TypeDef;
var reason = "";
if (td.tag == TypeDefTag.Enum) {
renderEnum(body, td);
} else if (td.tag == TypeDefTag.Flags) {
renderFlags(body, td);
} else if (td.tag == TypeDefTag.Record) {
reason = renderRecord(body, td, iface.def.items, uses);
} else if (td.tag == TypeDefTag.Variant) {
reason = renderVariant(body, td, iface.def.items, uses);
} else if (td.tag == TypeDefTag.Resource) {
renderResource(body, skipped, td, interfaceName,
iface.def.items, uses);
} else if (td.tag != TypeDefTag.Alias) {
reason = "types wait on the interop stages";
}
if (reason != "") {
skipped.append("// ").append(td.name.name).append(": ")
.append(reason).append("\n");
}
}
continue;
}
let nf = item.func as NamedFunc;
let rendered = renderFunc(body, nf, interfaceName, iface.def.items,
uses);
if (rendered != "") {
skipped.append("// ").append(nf.name.name).append(": ")
.append(rendered).append("\n");
}
}
drainHelpers(body, uses, interfaceName);
emitHelperTrailer(body, uses);
if (uses.fixedArray) {
sb.append("import { FixedArray } from 'zena:core';\n");
}
if (uses.array) {
sb.append("import { Array } from 'zena:core';\n");
}
if (uses.option) {
sb.append("import { Option, Some, some, none } from 'zena:core';\n");
}
if (uses.result) {
sb.append("import { Result } from 'zena:core';\n");
}
if (uses.stream) {
sb.append(streamImport(uses));
}
if (uses.abi.length > 0) {
sb.append("import { ");
for (var i = 0; i < uses.abi.length; i += 1) {
if (i > 0) { sb.append(", "); }
sb.append(uses.abi[i]);
}
sb.append(" } from 'zena:wasi';\n");
}
if (uses.componentStream.length > 0) {
sb.append("import { ");
for (var i = 0; i < uses.componentStream.length; i += 1) {
if (i > 0) { sb.append(", "); }
sb.append(uses.componentStream[i]);
}
sb.append(" } from 'zena:wasi';\n");
}
// Sibling synthesized modules whose types this interface `use`s:
// the declarations live there, so this module imports them.
{
let specifiers = new Array<String>();
for (let u in usedTypeImports) {
var known = false;
for (let s in specifiers) {
if (s == u.specifier) { known = true; }
}
if (!known) { specifiers.push(u.specifier); }
}
for (let spec in specifiers) {
sb.append("import { ");
var first = true;
for (let u in usedTypeImports) {
if (u.specifier != spec) { continue; }
if (!first) { sb.append(", "); }
first = false;
sb.append(u.name);
}
sb.append(" } from '").append(spec).append("';\n");
}
}
if (uses.anyResource) {
sb.append("import { Disposable } from 'zena:core';\n");
}
sb.append(handleImports(uses));
if (uses.error) {
sb.append("import { Error } from 'zena:core';\n");
}
if (uses.deferred) {
sb.append("import { DeferredFuture } from 'zena:async';\n");
}
if (uses.hasAsync && uses.awaitWaitable) {
sb.append("import { awaitPacked, awaitWaitable } " +
"from 'zena:wasi';\n");
} else if (uses.hasAsync) {
sb.append("import { awaitPacked } from 'zena:wasi';\n");
} else if (uses.awaitWaitable) {
sb.append("import { awaitWaitable } from 'zena:wasi';\n");
}
if (reinterpretUsed) {
sb.append(reinterpretImport);
}
sb.append(body.toString());
let skippedText = skipped.toString();
if (skippedText != "") {
sb.append("// Not yet importable from this interface ")
.append("(docs/design/component-model.md):\n")
.append(skippedText);
}
return sb.toString();
}
/**
* The lift and future helpers registered so far, into `body`. Lift
* helpers registered while rendering may register more as they are
* emitted (a record's field lifting a nested option), so this drains
* a worklist rather than walking a snapshot. Future helpers join the
* same drain: emitting one may register payload lift helpers, and a
* payload may register further futures. A future's canon type is
* named against `interfaceName` — the interface whose function moved
* it, which is where its payload's named types resolve — so a module
* that renders several interfaces' functions drains after each.
*/
function drainHelpers(body: StringBuilder, uses: SynthUses,
interfaceName: String): void {
while (uses.emittedLifts < uses.lifts.length ||
uses.emittedFlatLifts < uses.flatLifts.length ||
uses.emittedFutures < uses.futures.length ||
uses.emittedStreams < uses.streams.length) {
while (uses.emittedLifts < uses.lifts.length) {
let entry = uses.lifts[uses.emittedLifts];
uses.emittedLifts += 1;
emit(body, "", emitLiftHelper(entry, uses));
body.append("\n");
}
while (uses.emittedFlatLifts < uses.flatLifts.length) {
let entry = uses.flatLifts[uses.emittedFlatLifts];
uses.emittedFlatLifts += 1;
emit(body, "", emitFlatLiftHelper(entry, uses));
body.append("\n");
}
if (uses.emittedFutures < uses.futures.length) {
emitFutureHelpers(body, uses.futures[uses.emittedFutures],
interfaceName, uses);
uses.emittedFutures += 1;
}
if (uses.emittedStreams < uses.streams.length) {
emitStreamHelpers(body, uses.streams[uses.emittedStreams],
interfaceName, uses);
uses.emittedStreams += 1;
}
}
}
/**
* The table behind each resource the program provides: instances by
* representation (the index a handle carries), the registration a
* constructor or an own result goes through, the lookup a method's
* `self` or a borrowed parameter goes through, the destructor the
* host calls when the last handle over an instance is dropped, and
* the canon `resource.new` that mints a handle over a representation.
* The destructor frees the slot for reuse and disposes the instance:
* the class behind a resource is a `Disposable`, the way the handle
* class a consumer gets is, and its `dispose` is what the destructor
* means. A class that is not one fails the wrapper's type check. An
* own handle arriving as a parameter is the caller giving the instance
* up: it is taken back out of the table and handed to the program as
* the class, and the handle dropped — which reaches the destructor,
* which finds the slot already cleared and disposes nothing.
*/
function emitProgramResourceTables(body: StringBuilder,
uses: SynthUses) {
for (let r in programResources) {
uses.array = true;
let prefix = camelName(r.witName);
let table = `${prefix}Table`;
body.append("\n");
emit(body, "", zena`
/** The program's ${r.className} instances behind WIT resource
* ${r.witName}, by representation, and the slots freed by the
* destructor. */
let ${table} = new Array<${r.className} | null>();
let ${prefix}Free = new Array<i32>();
function ${prefix}Register(value: ${r.className}): i32 {
if (${prefix}Free.length > 0) {
let rep = ${prefix}Free.pop();
${table}[rep] = value;
return rep;
}
${table}.push(value);
return ${table}.length - 1;
}
function ${prefix}At(rep: i32): ${r.className} {
return ${table}[rep] as ${r.className};
}
/** An own handle arriving: the caller gave the instance up, so it
* leaves the table and goes to the program as the class. The
* handle is dropped, which reaches the destructor below with the
* slot already cleared, so nothing is disposed. */
function ${prefix}Take(handle: i32): ${r.className} {
let rep = ${prefix}Rep_raw(handle);
let value = ${table}[rep] as ${r.className};
${table}[rep] = null;
${prefix}Drop_raw(handle);
${prefix}Free.push(rep);
return value;
}
/** The destructor: the host calls it when the last handle over
* the instance at rep is dropped, from whichever component held
* it. The class is a Disposable, and this is its dispose. */
export function ${prefix}__dtor(rep: i32): void {
let value = ${table}[rep];
if (value == null) {
return;
}
${table}[rep] = null;
${prefix}Free.push(rep);
(value as ${r.className}).[Disposable.dispose]();
}
@external("canon", "resource.new#${r.qualified}#${r.witName}", "resource:${r.qualified}#${r.witName}")
declare function ${prefix}New_raw(rep: i32): i32;
@external("canon", "resource.rep#${r.qualified}#${r.witName}", "resource:${r.qualified}#${r.witName}")
declare function ${prefix}Rep_raw(handle: i32): i32;
@external("canon", "resource.drop#${r.qualified}#${r.witName}", "resource:${r.qualified}#${r.witName}")
declare function ${prefix}Drop_raw(handle: i32): void;
`);
body.append("\n");
}
}
/** The helpers a rendered module owes once, after every drain: the
* bare-result stand-in and the enum discriminant checks. */
function emitHelperTrailer(body: StringBuilder, uses: SynthUses): void {
if (uses.unit) {
body.append("/** The one spellable void value: a bare result ")
.append("arm's stand-in. */\n");
body.append("function witUnit(): void {}\n");
}
for (let lifted in uses.enumLifts) {
// The host is obligated to produce a valid discriminant, but a
// range check is one compare, and an out-of-range value cast
// silently into an enum would defeat exhaustive matching somewhere
// far from here.
body.append("function lift").append(lifted.typeName)
.append("(disc: i32): ").append(lifted.typeName)
.append(" {\n if (disc < 0 || disc >= ")
.append(i32ToString(lifted.caseCount))
.append(") {\n throw new Error('invalid ")
.append(lifted.typeName).append(" discriminant');\n }\n")
.append(" return disc as ").append(lifted.typeName)
.append(";\n}\n");
}
}
/**
* Render one function — a plain `@external` declaration when
* everything is a flat scalar, a raw declaration plus a marshaling or
* future wrapper otherwise — or return the reason it cannot be
* rendered yet.
*/
/** How one WIT function renders: as a free function, or as a member
* of a synthesized resource class. */
final class FnMode {
/** The `@external` field name: the WIT name, or a mangled
* `[method]r.f` / `[static]r.f` / `[constructor]r`. */
externField: String;
/** The Zena name of the wrapper. */
zenaName: String;
/** The raw declaration's name (module-level, so resource-prefixed). */
rawName: String;
/** The wrapper's declaration head: `"export function "` for a free
* function, `""` for a method, `"static "` for a static or a WIT
* constructor. */
declHead: String;
/** Whether the raw call leads with `this.#handle`. */
selfHandle: boolean;
/** A WIT constructor's implicit `own` result: the resource's WIT
* name, or "" for everything else. */
ctorResource: String;
new(this.externField, this.zenaName, this.rawName, this.declHead,
this.selfHandle, this.ctorResource = "");
}
/** Zena keywords a WIT name may collide with (`new: static func` is
* real, in wasi:http); the member gets a trailing underscore, which no
* other synthesized name contains. */
function zenaMemberName(witName: String): String {
let camel = camelName(witName);
if (camel == "new" || camel == "match" || camel == "let" ||
camel == "var" || camel == "function" || camel == "return" ||
camel == "this" || camel == "class" || camel == "enum" ||
camel == "type" || camel == "import" || camel == "export" ||
camel == "using" || camel == "true" || camel == "false" ||
camel == "null" || camel == "if" || camel == "else" ||
camel == "for" || camel == "while" || camel == "in" ||
camel == "is" || camel == "as" || camel == "case") {
return camel + "_";
}
return camel;
}
function renderFunc(
sb: StringBuilder,
nf: NamedFunc,
interfaceName: String,
ifaceItems: GrowableArray<InterfaceItem>,
uses: SynthUses
): String {
let zenaName = camelName(nf.name.name);
return renderFuncIn(sb, sb, nf, interfaceName, ifaceItems, uses,
new FnMode(nf.name.name, zenaName, zenaName, "export function ",
false));
}
/**
* The spilled parameters of one call: a staged buffer holding the
* `self` handle (a method's first parameter) and then each parameter
* at its aligned offset, lowered the way a record's fields are. The
* buffer is arena-tracked, so the wrapper's release after the call
* frees it with everything else it staged — after the subtask has
* returned, for an async lowering, since the callee reads the
* parameters out of the caller's memory when it starts.
*/
function emitSpilledParams(sb: StringBuilder, params: GrowableArray<Ty>,
paramNames: GrowableArray<String>, selfHandle: boolean,
uses: SynthUses) {
var offset = 0;
var maxAlign = 1;
let offsets = new Array<i32>();
if (selfHandle) {
offset = 4;
maxAlign = 4;
}
for (let p in params) {
if (p.align > maxAlign) { maxAlign = p.align; }
offset = alignTo(offset, p.align);
offsets.push(offset);
offset += p.size;
}
let size = `${alignTo(offset, maxAlign)}`;
uses.useAbi("stageBuffer");
uses.stagedAny = true;
let stores = new Array<ZenaTemplate>();
if (selfHandle) {
uses.useAbi("storeI32");
stores.push(zena`storeI32(args, this.#handle);`);
}
for (var i = 0; i < params.length; i += 1) {
let at = if (offsets[i] == 0) "args" else `args + ${offsets[i]}`;
stores.push(lowerMemStmts(params[i], paramNames[i], at, uses));
}
emit(sb, " ", zena`
let args = stageBuffer(${size});
${stores}
`);
sb.append("\n");
}
/**
* Render one function into `wrapSink` (the wrapper) and `rawSink`
* (the raw declaration — module level, which for a resource member is
* a different sink than the class body). Returns the reason it cannot
* be rendered yet, or "".
*/
function renderFuncIn(
wrapSink: StringBuilder,
rawSink: StringBuilder,
nf: NamedFunc,
interfaceName: String,
ifaceItems: GrowableArray<InterfaceItem>,
uses: SynthUses,
mode: FnMode
): String {
let func = nf.func;
let params = new Array<Ty>();
let paramNames = new Array<String>();
var anyRich = false;
for (var i = 0; i < func.params.length; i += 1) {
let wire = classifyType(func.params[i].type, ifaceItems);
if (wire.kind == TyKind.Unsupported) {
return `parameter '${func.params[i].name.name}': ${wire.reason}`;
}
let blocked = lowerBlocker(wire);
if (blocked != "") {
return `parameter '${func.params[i].name.name}': ${blocked}`;
}
if (flatCoreSlots(wire) == null) {
return "parameter '" + func.params[i].name.name +
"': its variant payloads join across core types, which " +
"waits on the interop stages";
}
if (wire.kind != TyKind.Scalar) {
anyRich = true;
}
params.push(wire);
// The same keyword mangling members get: wasi:http spells
// `consume-body: static func(this: request, ...)`, and `this` is
// not a parameter name Zena will take.
paramNames.push(zenaMemberName(func.params[i].name.name));
}
var paramFlats = 0;
for (let p in params) {
paramFlats += (flatCoreSlots(p) as GrowableArray<String>).length;
}
// Past sixteen core values in a synchronous lowering, or four in an
// asynchronous one, the parameters — a method's `self` handle among
// them — travel as one address: the wrapper lays them out in memory
// it owns, back to back at their aligned offsets, and the raw call
// takes that address alone. The encoder counts the same way.
let selfFlats = if (mode.selfHandle) 1 else 0;
let paramsSpill =
paramFlats + selfFlats > (if (func.isAsync) 4 else 16);
var resultTy = voidTy();
var hasResult = false;
if (mode.ctorResource != "") {
// A WIT constructor returns `own<resource>` implicitly.
hasResult = true;
resultTy = classifyNamed(mode.ctorResource, ifaceItems);
}
let result = func.result;
if (result != null) {
hasResult = true;
resultTy = classifyType(result as Type, ifaceItems);
if (resultTy.kind == TyKind.Unsupported) {
return "the result: " + resultTy.reason;
}
let blocked = liftBlocker(resultTy, false);
if (blocked != "") {
return "the result: " + blocked;
}
if (resultTy.kind != TyKind.Scalar) {
anyRich = true;
}
// A bare `-> result` (both arms void) is one discriminant on the
// wire, returned directly and rebuilt from `witUnit()` lanes.
let bareResult = resultTy.kind == TyKind.ResultT &&
isVoid(resultTy.children[0]) && isVoid(resultTy.children[1]);
if (resultTy.flats == 1 && !bareResult &&
resultTy.kind != TyKind.Enumeration &&
resultTy.kind != TyKind.Flags && resultTy.kind != TyKind.Scalar &&
resultTy.kind != TyKind.ResourceH &&
resultTy.kind != TyKind.StreamH &&
resultTy.kind != TyKind.FutureH) {
return "a single-flat aggregate result waits on the interop stages";
}
}
let zenaName = mode.zenaName;
let freeMode = mode.declHead == "export function " && !mode.selfHandle;
if (func.isAsync) {
if (!anyRich && !hasResult && freeMode && !paramsSpill) {
// Flat scalars, no result: the thin form. The raw import's core
// result is the packed `(subtask << 4) | state` the canonical
// `async` lowering returns; `awaitPacked` turns it into the
// future. The `_raw` suffix cannot collide with another
// rendered function: WIT names are kebab-case, so no camelName
// output contains an underscore.
uses.hasAsync = true;
let sig = new StringBuilder();
let args = new StringBuilder();
for (var i = 0; i < params.length; i += 1) {
if (i > 0) {
sig.append(", ");
args.append(", ");
}
sig.append(paramNames[i]).append(": ").append(params[i].scalar);
args.append(paramNames[i]);
}
rawSink.append("@external(\"").append(interfaceName)
.append("\", \"").append(nf.name.name)
.append("\", \"async\")\n");
rawSink.append("declare function ").append(zenaName)
.append("_raw(").append(sig.toString()).append("): i32;\n");
rawSink.append("export function ").append(zenaName)
.append("(").append(sig.toString())
.append("): Future<void> {\n return awaitPacked(")
.append(zenaName).append("_raw(").append(args.toString())
.append("));\n}\n");
return "";
}
// Anything richer — and every resource function, whose `self`
// handle the general path prefixes — takes the general path
// below as an async wrapper: stage, call, await the subtask, then
// lift the result the host wrote through the trailing return area
// — an async lowering spills any result, whatever its flat count.
}
// The result spills — the raw call takes a return area address and
// returns nothing — exactly when it flattens to more than one core
// value. An async result always spills.
let resultSpills = if (func.isAsync) hasResult else resultTy.flats > 1;
if (!anyRich && freeMode && !paramsSpill && !func.isAsync) {
// Every type is a flat scalar: one declaration, no wrapper. An
// async function with a result never is: its result rides the
// trailing return area, so it takes the wrapper below.
let sig = new StringBuilder();
for (var i = 0; i < params.length; i += 1) {
if (i > 0) { sig.append(", "); }
sig.append(paramNames[i]).append(": ").append(params[i].scalar);
}
rawSink.append("@external(\"").append(interfaceName).append("\", \"")
.append(nf.name.name).append("\")\n");
rawSink.append("export declare function ").append(zenaName)
.append("(").append(sig.toString()).append("): ")
.append(if (hasResult) resultTy.scalar else "void")
.append(";\n");
return "";
}
// The raw declaration: staged strings and lists are (ptr, len)
// pairs, an aggregate is its flattened core slots, and a spilled
// result appends the return area address.
let aggregate = (kind: TyKind) =>
kind == TyKind.ListT || kind == TyKind.RecordT ||
kind == TyKind.VariantT || kind == TyKind.OptionT ||
kind == TyKind.TupleT;
let rawSig = new StringBuilder();
var rawIndex = 0;
if (paramsSpill) {
rawSig.append("args: i32");
rawIndex += 1;
} else if (mode.selfHandle) {
rawSig.append("self: i32");
rawIndex += 1;
}
for (var i = 0; i < params.length && !paramsSpill; i += 1) {
if (rawIndex > 0) { rawSig.append(", "); }
if (params[i].kind == TyKind.Scalar) {
rawSig.append("a").append(i32ToString(i)).append(": ")
.append(params[i].scalar);
rawIndex += 1;
} else if (params[i].kind == TyKind.Enumeration) {
rawSig.append("a").append(i32ToString(i)).append(": i32");
rawIndex += 1;
} else if (params[i].kind == TyKind.Flags) {
rawSig.append("a").append(i32ToString(i)).append(": u32");
rawIndex += 1;
} else if (params[i].kind == TyKind.ResourceH ||
params[i].kind == TyKind.StreamH ||
params[i].kind == TyKind.FutureH) {
rawSig.append("a").append(i32ToString(i)).append(": i32");
rawIndex += 1;
} else if (aggregate(params[i].kind)) {
let slots = flatCoreSlots(params[i]) as GrowableArray<String>;
for (var k = 0; k < slots.length; k += 1) {
if (k > 0) { rawSig.append(", "); }
rawSig.append("s").append(i32ToString(i)).append("_")
.append(i32ToString(k)).append(": ").append(slots[k]);
}
rawIndex += slots.length;
} else {
rawSig.append("p").append(i32ToString(i)).append(": i32, l")
.append(i32ToString(i)).append(": i32");
rawIndex += 2;
}
}
if (resultSpills) {
if (rawIndex > 0) { rawSig.append(", "); }
rawSig.append("ret: i32");
}
let rawResult = if (func.isAsync) {
"i32"
} else if (resultSpills || !hasResult) {
"void"
} else if (resultTy.kind == TyKind.Enumeration) {
"i32"
} else if (resultTy.kind == TyKind.Flags) {
"u32"
} else if (resultTy.kind == TyKind.ResourceH ||
resultTy.kind == TyKind.StreamH ||
resultTy.kind == TyKind.FutureH ||
resultTy.kind == TyKind.ResultT) {
// A non-spilled result is the bare `-> result`: one discriminant.
"i32"
} else {
resultTy.scalar
};
rawSink.append("@external(\"").append(interfaceName).append("\", \"")
.append(mode.externField);
if (func.isAsync) {
rawSink.append("\", \"async");
}
rawSink.append("\")\n");
rawSink.append("declare function ").append(mode.rawName)
.append("_raw(").append(rawSig.toString()).append("): ")
.append(rawResult).append(";\n");
// The wrapper: the WIT signature in Zena spellings, staging in,
// lifting out. Built into its own buffer so a member wrapper can be
// reindented into the class body.
let sb = new StringBuilder();
let wrapSig = new StringBuilder();
for (var i = 0; i < params.length; i += 1) {
if (i > 0) { wrapSig.append(", "); }
wrapSig.append(paramNames[i]).append(": ")
.append(zenaTypeOf(params[i], uses));
}
let bothArmsVoid = resultTy.kind == TyKind.ResultT &&
isVoid(resultTy.children[0]) && isVoid(resultTy.children[1]);
var wrapResult = "void";
if (hasResult) {
if (bothArmsVoid && !func.isAsync) {
// A bare `-> result` has exactly two outcomes and no payloads:
// a boolean, true for ok. The inline Result cannot carry two
// zero-width lanes.
wrapResult = "boolean";
} else if (resultTy.kind == TyKind.ResultT) {
if (func.isAsync) {
// A future's payload is stored, so the async form carries a
// stored result.
wrapResult = storedResultType(resultTy, uses);
} else {
uses.result = true;
wrapResult = "inline Result<" +
zenaTypeOf(resultTy.children[0], uses) + ", " +
zenaTypeOf(resultTy.children[1], uses) + ">";
}
} else {
wrapResult = zenaTypeOf(resultTy, uses);
}
}
var declHead = mode.declHead;
if (func.isAsync) {
uses.hasAsync = true;
// A free function exports; a method, static or constructor keeps
// its member head with `async` in front.
declHead = if (freeMode) "export async function "
else mode.declHead + "async ";
wrapResult = `Future<${wrapResult}>`;
}
sb.append(declHead).append(zenaName).append("(")
.append(wrapSig.toString()).append("): ").append(wrapResult)
.append(" {\n");
// Release is by arena range: an async wrapper suspended on its
// subtask still owns live staging (the callee may lift arguments
// after the call returns), so each wrapper frees exactly what it
// staged and nothing an interleaved wrapper still owes.
var anyStaging = paramsSpill;
for (let p in params) {
if (mayStage(p)) {
anyStaging = true;
}
}
if (anyStaging) {
uses.useAbi("stagedMark");
uses.useAbi("releaseStagedFrom");
sb.append(" let m0 = stagedMark();\n");
}
let callArgs = new StringBuilder();
var argIndex = 0;
if (paramsSpill) {
emitSpilledParams(sb, params, paramNames, mode.selfHandle, uses);
callArgs.append("args");
argIndex += 1;
}
for (var i = 0; i < params.length && !paramsSpill; i += 1) {
if (argIndex > 0) { callArgs.append(", "); }
if (params[i].kind == TyKind.Scalar) {
callArgs.append(paramNames[i]);
argIndex += 1;
continue;
}
if (params[i].kind == TyKind.Enumeration) {
callArgs.append(paramNames[i]).append(" as i32");
argIndex += 1;
continue;
}
if (params[i].kind == TyKind.Flags) {
callArgs.append(paramNames[i]).append(" as u32");
argIndex += 1;
continue;
}
if (params[i].kind == TyKind.ResourceH) {
let h = "h" + i32ToString(i);
if (params[i].ownedClass) {
sb.append(" let ").append(h).append(" = ")
.append(loweredHandle(params[i], paramNames[i], uses))
.append(";\n");
callArgs.append(h);
argIndex += 1;
continue;
}
uses.useAbi("rawHandle");
sb.append(" let ").append(h).append(" = ").append(paramNames[i])
.append(".[rawHandle]();\n");
if (!params[i].isBorrow) {
// An owned handle transfers to the callee: the wrapper's
// later dispose must not drop an index it no longer owns.
uses.useAbi("markMoved");
sb.append(" ").append(paramNames[i])
.append(".[markMoved]();\n");
}
callArgs.append(h);
argIndex += 1;
continue;
}
if (params[i].kind == TyKind.StreamH) {
callArgs.append(streamLowerCall(params[i], paramNames[i], uses));
argIndex += 1;
continue;
}
if (params[i].kind == TyKind.FutureH) {
callArgs.append("lowerFuture")
.append(i32ToString(uses.futureIndexOf(params[i])))
.append("(").append(paramNames[i]).append(")");
argIndex += 1;
continue;
}
if (aggregate(params[i].kind)) {
// Zero-initialized slot variables, then the lowering statements:
// an untaken option or a shorter variant arm leaves its slots at
// zero, which the canonical ABI never reads.
let slots = flatCoreSlots(params[i]) as GrowableArray<String>;
currentSlotTypes = slots;
let slotNames = new Array<String>();
for (var k = 0; k < slots.length; k += 1) {
let slotName = `s${i32ToString(i)}_${i32ToString(k)}`;
slotNames.push(slotName);
let zero = if (slots[k] == "f32" || slots[k] == "f64") "0.0"
else "0";
sb.append(" var ").append(slotName).append(": ")
.append(slots[k]).append(" = ").append(zero).append(";\n");
}
lowerFlatStmts(sb, params[i], paramNames[i], slotNames, 0, " ",
uses);
for (var k = 0; k < slotNames.length; k += 1) {
if (k > 0) { callArgs.append(", "); }
callArgs.append(slotNames[k]);
}
argIndex += slotNames.length;
continue;
}
let stage = if (params[i].kind == TyKind.Str) {
"stageString"
} else {
"stageByteList"
};
uses.useAbi(stage);
uses.stagedAny = true;
sb.append(" let (p").append(i32ToString(i)).append(", l")
.append(i32ToString(i)).append(") = ").append(stage)
.append("(").append(paramNames[i]).append(");\n");
callArgs.append("p").append(i32ToString(i)).append(", l")
.append(i32ToString(i));
argIndex += 2;
}
if (resultSpills) {
uses.useAbi("resultArea");
sb.append(" let ret = resultArea(")
.append(i32ToString(resultTy.size)).append(");\n");
if (argIndex > 0) { callArgs.append(", "); }
callArgs.append("ret");
}
let callPrefix = if (mode.selfHandle && !paramsSpill) {
if (callArgs.toString() == "") "this.#handle"
else "this.#handle, "
} else {
""
};
let call = `${mode.rawName}_raw(${callPrefix}${callArgs.toString()})`;
if (func.isAsync) {
// The call hands back the packed subtask; the await parks until
// the host reports it returned — which is also when the trailing
// return area holds the result and the staged arguments are
// certainly consumed.
sb.append(" let packed = ").append(call).append(";\n");
sb.append(" await awaitPacked(packed);\n");
} else if (resultSpills || rawResult == "void") {
sb.append(" ").append(call).append(";\n");
} else {
sb.append(" let got = ").append(call).append(";\n");
}
// A synchronous lowering consumed the staged arguments during the
// call; an asynchronous one has by the time the subtask returned.
if (anyStaging) {
sb.append(" releaseStagedFrom(m0);\n");
}
if (resultSpills) {
uses.useAbi("freeLifted");
if (resultTy.kind == TyKind.ResultT) {
// A top-level result lifts into the inline Result, or, from an
// async wrapper, into the stored Result a future carries.
let payoff = payloadOffset(resultTy);
let okZ = zenaTypeOf(resultTy.children[0], uses);
let errZ = zenaTypeOf(resultTy.children[1], uses);
// A bare arm has no bytes to lift and no local to bind — a
// `void` local is not a thing — so its value is a `witUnit()`
// call in argument position.
var okExpr = "ok";
var errExpr = "err";
if (isVoid(resultTy.children[0])) {
uses.unit = true;
okExpr = "witUnit()";
}
if (isVoid(resultTy.children[1])) {
uses.unit = true;
errExpr = "witUnit()";
}
sb.append(" if (").append(discLoad(1, "ret", uses))
.append(" == 0) {\n");
if (okExpr == "ok") {
sb.append(" let ok = ")
.append(liftExprOf(resultTy.children[0],
"ret + " + i32ToString(payoff), uses))
.append(";\n");
}
sb.append(" freeLifted(ret);\n");
sb.append(" return ").append(okResultExpr(okExpr))
.append(";\n }\n");
if (errExpr == "err") {
sb.append(" let err = ")
.append(liftExprOf(resultTy.children[1],
"ret + " + i32ToString(payoff), uses))
.append(";\n");
}
sb.append(" freeLifted(ret);\n");
sb.append(" return ").append(errResultExpr(errExpr))
.append(";\n");
} else {
sb.append(" let out = ")
.append(liftExprOf(resultTy, "ret", uses)).append(";\n");
sb.append(" freeLifted(ret);\n");
sb.append(" return out;\n");
}
} else if (resultTy.kind == TyKind.Enumeration) {
uses.needEnumLift(resultTy);
sb.append(" return lift").append(resultTy.typeName)
.append("(got);\n");
} else if (resultTy.kind == TyKind.Flags) {
sb.append(" return got as ").append(resultTy.typeName)
.append(";\n");
} else if (resultTy.kind == TyKind.ResourceH) {
sb.append(" return ").append(liftedHandle(resultTy, "got", uses))
.append(";\n");
} else if (resultTy.kind == TyKind.StreamH) {
sb.append(" return ").append(streamLiftCall(resultTy, "got", uses))
.append(";\n");
} else if (resultTy.kind == TyKind.FutureH) {
sb.append(" return liftFuture")
.append(i32ToString(uses.futureIndexOf(resultTy)))
.append("(got);\n");
} else if (resultTy.kind == TyKind.ResultT) {
// The bare `-> result`: the wire value is the discriminant, and
// the Zena shape is a boolean, true for ok.
sb.append(" return got == 0;\n");
} else if (!func.isAsync && rawResult != "void") {
sb.append(" return got;\n");
}
sb.append("}\n");
if (freeMode) {
wrapSink.append(sb.toString());
} else {
// A member: two spaces onto every non-empty line.
for (let line in sb.toString().split("\n")) {
if (line != "") {
wrapSink.append(" ").append(line);
}
wrapSink.append("\n");
}
}
return "";
}
/**
* One async function export of a declared world: at world level, or
* of an exported interface, whose entry in the interfaces list,
* qualified name (the `return:` scope) and module specifier it then
* carries.
*/
final class AsyncWorldExport {
name: String;
func: Func;
var interfaceIndex = -1;
var qualifiedInterface = "";
var specifier = "";
/** For a resource's function: the resource's WIT name, the kind
* ("constructor", "method", "static") and the member's WIT name. */
var resourceName = "";
var kind = "";
var member = "";
new(this.name, this.func);
/** The wrapper's target: the class for a resource's function, the
* function itself otherwise. */
target(): ExportTarget {
if (this.resourceName == "") {
return new ExportTarget(this.name, camelName(this.name));
}
let prefix = camelName(this.resourceName);
let memberZena = if (this.kind == "constructor") ""
else zenaMemberName(this.member);
return new ExportTarget(this.name,
resourceWrapperBase(prefix, this.kind, camelName(this.member)),
pascalName(this.resourceName), this.resourceName, this.kind,
memberZena);
}
}
/**
* The entry wrapper for a program compiled against a declared world
* (`--wit`/`--world`): one `<name>_export` function per async
* function export of the world, each declaring `task.return` at the
* export's result type, plus `main`'s own wrapper when it returns a
* scalar (component-entry.zena). Null when the program needs neither.
*
* A wrapper takes the export's flattened core parameters as the
* canonical ABI hands them to the lift — a string as its pointer and
* length in linear memory — lifts them, calls the program's function,
* and hands the driver its future together with the typed return,
* which lowers the future's value to the return's flat parameters
* through the same staging the import wrappers use. Parameters may be
* flat scalars and strings; a result may be anything the import path
* lowers, a `result` carried as a stored `Result`. Named types are not
* resolvable at world level yet (they need world-level `use`), and
* anything refused fails the compile with the reason: the world
* declares the export async, and nothing else could implement it.
*/
export function synthesizeExportWrapper(
witSource: String,
worldName: String,
entryPath: String,
entryAst: Module,
packagesWit: String = ""
): ComponentEntryWrapper | null {
// With the compiler's WASI WIT and the program's WIT-backed packages
// riding along, as the declared-world encoder parses it.
let source = withWasiPackages(witSource, packagesWit);
let ast = parsedWit(source);
var world: WorldDef | null = null;
for (let item in ast.items) {
if (item.tag == AstItemTag.World) {
let def = item.worldDef as WorldDef;
if (world == null && (worldName == "" || def.name.name == worldName)) {
world = def;
}
}
}
// World-level async function exports, and the async functions of
// each exported interface, which land in an instance of the
// interface's name and resolve their named types through its
// `use`s.
let exports = new Array<AsyncWorldExport>();
let interfaces = new Array<FoundInterface>();
let interfaceExports = new Array<AsyncWorldExport>();
let noItemsForWorld = new Array<InterfaceItem>();
if (world != null) {
for (let wi in expandedWorldItems(ast, world)) {
if (wi.tag != WorldItemTag.Export) { continue; }
let kind = (wi.exportItem as Export).kind;
if (kind.tag == ExternKindTag.Func) {
let func = kind.funcDef as Func;
if (!func.isAsync && !needsSyncWrapper(func, noItemsForWorld)) {
continue;
}
let name = (kind.name as Id).name;
// The world's async `main` is the entry: the component lifts
// the program's async main on its own, with its typed return
// declared by the entry wrapper (lib/component-entry.zena), and
// a second wrapper here would export the name twice.
if (name == "main" && hasAsyncMain(entryAst)) { continue; }
exports.push(new AsyncWorldExport(name, func));
} else if (kind.tag == ExternKindTag.Path) {
let path = kind.path as UsePath;
var namespace = "";
var interfacePath = "";
if (path.tag == UsePathTag.Id) {
let main = ast.packageName as PackageName;
namespace = main.namespace.name;
interfacePath = `${main.name.name}/${(path.id as Id).name}`;
} else {
let pkg = path.packageId as PackageName;
namespace = pkg.namespace.name;
interfacePath = `${pkg.name.name}/${(path.name as Id).name}`;
}
let found = findInterfaceOrNull(ast, namespace, interfacePath);
if (found == null) {
throw new Error("The declared world exports '" + namespace + ":" +
interfacePath + "', which the document does not declare.");
}
let iface = found as FoundInterface;
var qualified = `${namespace}:${interfacePath}`;
let version = iface.packageName.version;
if (version != null) {
qualified = `${qualified}@${version as String}`;
}
for (let item in iface.def.items) {
if (item.tag == InterfaceItemTag.TypeDef) {
// A resource the program provides: every function of it
// goes through a wrapper — a method's first parameter is
// the representation to look the instance up by.
let td = item.typeDef as TypeDef;
if (td.tag != TypeDefTag.Resource) { continue; }
for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
var kind = "method";
var member = rf.func.name.name;
var name = `[method]${td.name.name}.${member}`;
if (rf.tag == ResourceFuncTag.Constructor) {
kind = "constructor";
member = "";
name = "[constructor]" + td.name.name;
} else if (rf.tag == ResourceFuncTag.Static) {
kind = "static";
name = `[static]${td.name.name}.${member}`;
}
let e = new AsyncWorldExport(name, rf.func.func);
e.interfaceIndex = interfaces.length;
e.qualifiedInterface = qualified;
e.specifier = `${namespace}:${interfacePath}`;
e.resourceName = td.name.name;
e.kind = kind;
e.member = member;
interfaceExports.push(e);
}
continue;
}
if (item.tag != InterfaceItemTag.Func) { continue; }
let nf = item.func as NamedFunc;
if (!nf.func.isAsync &&
!needsSyncWrapper(nf.func, iface.def.items)) {
continue;
}
let e = new AsyncWorldExport(nf.name.name, nf.func);
e.interfaceIndex = interfaces.length;
e.qualifiedInterface = qualified;
e.specifier = `${namespace}:${interfacePath}`;
interfaceExports.push(e);
}
exportedInterfaces.push(new ExportedInterface(
`${namespace}:${interfacePath}`, qualified));
interfaces.push(iface);
}
}
}
let mainResult = mainWrapperResultOf(entryAst);
let mainIsAsync = hasAsyncMain(entryAst);
if (exports.length == 0 && interfaceExports.length == 0 &&
mainResult == "") {
return null;
}
currentWitSource = source;
currentAst = ast;
currentEntryAst = entryAst;
currentPackage = ast.packageName;
selfSpecifier = "";
currentSpecifier = "";
reinterpretUsed = false;
usedTypeImports = new Array<UsedTypeImport>();
programResources = new Array<ProgramResource>();
let noItems = new Array<InterfaceItem>();
let uses = new SynthUses();
let body = new StringBuilder();
let imported = new Array<String>();
let importFromEntry = (name: String) => {
for (let existing in imported) {
if (existing == name) { return; }
}
imported.push(name);
};
if (mainResult != "") {
imported.push("main");
for (let name in mainWrapperAbiImports(mainResult, mainIsAsync)) {
// Every wrapper imports `finishTask` already.
if (name != "finishTask") { uses.useAbi(name); }
}
renderMainWrapper(body, mainResult, mainIsAsync);
}
for (let e in exports) {
let target = e.target();
importFromEntry(target.base);
body.append("\n");
if (e.func.isAsync) {
renderExportWrapper(body, target, e.func, noItems, uses, "");
} else {
renderSyncExportWrapper(body, target, e.func, noItems, uses);
}
// A world-level export's future is structural: its canon type
// names no interface.
drainHelpers(body, uses, "");
}
for (let e in interfaceExports) {
let iface = interfaces[e.interfaceIndex];
// Types classify in the interface's own context: a `use`d type
// hops to its source module, which the wrapper then imports — and
// so does a type the interface declares itself, from the
// interface's own synthesized module, since the wrapper is not
// that module. Hence no `selfSpecifier`: nothing is local here.
currentPackage = iface.packageName;
selfSpecifier = "";
currentSpecifier = e.specifier;
let target = e.target();
if (target.resourceName != "") {
// The class comes from the entry; classifying the resource
// registers it for the table helpers below, and a constructor's
// result is an own of it.
importFromEntry(target.className);
let resourceTy = classifyNamed(target.resourceName, iface.def.items);
if (target.kind == "constructor") {
target.implicitResult = resourceTy;
}
if (isPluginKindCreate(target, e.func) &&
!classHasStatic(entryAst, target.className, target.member)) {
// A plugin kind's `create`: the wrapper writes it, returning
// the object the program registered under the token when it
// loaded the extension (zena:extensions, `claimPlugin`).
uses.plugin = true;
uses.error = true;
let fn = `${target.className}__create`;
target.calleeOverride = fn;
body.append("\n");
body.append("/** The plugin kind's create: the object the program registered under\n");
body.append(" * `token` when it loaded the extension, which must be a ")
.append(target.className).append(". */\n");
body.append("function ").append(fn).append("(token: u32): ")
.append(target.className).append(" {\n");
body.append(" let object = claimPlugin(token);\n");
body.append(" if (object is ").append(target.className).append(") {\n");
body.append(" return object;\n");
body.append(" }\n");
body.append(" throw new Error(if (object == null) ")
.append("`no plugin object was registered under token ${token}`")
.append(" else `the plugin object registered under token ${token} is not a ")
.append(target.className).append("`);\n");
body.append("}\n");
}
} else {
importFromEntry(target.base);
}
body.append("\n");
if (e.func.isAsync) {
renderExportWrapper(body, target, e.func, iface.def.items, uses,
e.qualifiedInterface);
} else {
renderSyncExportWrapper(body, target, e.func, iface.def.items, uses);
}
// A future this export moves — a `future<T>` result the program's
// `Future<T>` lowers into — gets its helpers here, typed against
// the exporting interface.
drainHelpers(body, uses, e.qualifiedInterface);
}
emitHelperTrailer(body, uses);
emitProgramResourceTables(body, uses);
exportedInterfaces = new Array<ExportedInterface>();
let specifier = componentEntrySpecifierFor(entryPath);
let sb = new StringBuilder();
renderWrapperHeader(sb);
sb.append("import { ");
for (var i = 0; i < imported.length; i += 1) {
if (i > 0) { sb.append(", "); }
sb.append(imported[i]);
}
sb.append(" } from '").append(specifier).append("';\n");
sb.append("import { finishTask, finishVoidTask } from 'zena:wasi';\n");
if (uses.plugin) {
sb.append("import { claimPlugin } from 'zena:extensions';\n");
}
if (uses.option) {
sb.append("import { Option, Some, some, none } from 'zena:core';\n");
}
if (uses.array) {
sb.append("import { Array } from 'zena:core';\n");
}
if (uses.fixedArray) {
sb.append("import { FixedArray } from 'zena:core';\n");
}
if (uses.error) {
sb.append("import { Error } from 'zena:core';\n");
}
if (programResources.length > 0) {
sb.append("import { Disposable } from 'zena:core';\n");
}
sb.append(handleImports(uses));
if (uses.result) {
sb.append("import { Result } from 'zena:core';\n");
}
if (uses.stream) {
sb.append(streamImport(uses));
}
if (uses.abi.length > 0) {
sb.append("import { ");
for (var i = 0; i < uses.abi.length; i += 1) {
if (i > 0) { sb.append(", "); }
sb.append(uses.abi[i]);
}
sb.append(" } from 'zena:wasi';\n");
}
if (uses.componentStream.length > 0) {
sb.append("import { ");
for (var i = 0; i < uses.componentStream.length; i += 1) {
if (i > 0) { sb.append(", "); }
sb.append(uses.componentStream[i]);
}
sb.append(" } from 'zena:wasi';\n");
}
if (uses.deferred) {
sb.append("import { DeferredFuture } from 'zena:async';\n");
}
if (uses.awaitWaitable) {
sb.append("import { awaitWaitable } from 'zena:wasi';\n");
}
if (reinterpretUsed) {
sb.append(reinterpretImport);
}
// The synthesized modules whose types the wrappers name: a resource
// parameter lifts into its class, a result lowers out of one.
{
let specifiers = new Array<String>();
for (let u in usedTypeImports) {
var known = false;
for (let s in specifiers) {
if (s == u.specifier) { known = true; }
}
if (!known) { specifiers.push(u.specifier); }
}
for (let spec in specifiers) {
sb.append("import { ");
var first = true;
for (let u in usedTypeImports) {
if (u.specifier != spec) { continue; }
if (!first) { sb.append(", "); }
first = false;
sb.append(u.name);
}
sb.append(" } from '").append(spec).append("';\n");
}
}
sb.append("\n").append(body.toString());
return new ComponentEntryWrapper(componentEntryPathFor(entryPath),
sb.toString(), specifier, entryPath);
}
/**
* Whether a declared synchronous export needs a wrapper: a parameter
* or result that is not a flat scalar or a string. Those two a
* program export lifts on its own (component-adapters wraps the
* string); anything richer is marshaled here, typed from the WIT.
*/
function needsSyncWrapper(func: Func, items: GrowableArray<InterfaceItem>): boolean {
let plain = (ty: Ty) =>
ty.kind == TyKind.Scalar || ty.kind == TyKind.Str;
// Past sixteen core values the host spills the parameters into
// memory and the lift takes one address, which only the wrapper
// knows to read.
var flats = 0;
for (let p in func.params) {
let ty = classifyType(p.type, items);
if (!plain(ty)) { return true; }
flats += if (ty.kind == TyKind.Str) 2 else 1;
}
if (flats > 16) { return true; }
let result = func.result;
return result != null && !plain(classifyType(result as Type, items));
}
/**
* What an export wrapper reaches in the program: a free function by
* name, or a resource's constructor, method or static through the
* program's class. `witName` is the component export name
* (`describe`, `[method]surface.on-frame`); `base` the wrapper's
* identifier base (`describe`, `surface__method__onFrame`), which
* `componentExportNameOf` reads the export name back from.
*/
/**
* Whether `target` is a plugin kind's `create`: a static `create` of
* a resource taking one `u32` and returning an own of that resource.
*/
function isPluginKindCreate(target: ExportTarget, func: Func): boolean {
if (target.kind != "static" || target.member != "create") {
return false;
}
if (func.params.length != 1 || func.params[0].type.tag != TypeTag.U32) {
return false;
}
let result = func.result;
if (result == null || (result as Type).tag != TypeTag.Own) {
return false;
}
let inner = (result as Type).inner;
return inner != null && (inner as Type).tag == TypeTag.Name &&
((inner as Type).name as Id).name == target.resourceName;
}
final class ExportTarget {
witName: String;
base: String;
/** The class behind a resource's function; "" for a free function. */
className: String;
/** The resource's WIT name; "" for a free function. */
resourceName: String;
/** "constructor", "method" or "static"; "" for a free function. */
kind: String;
/** The member's Zena name on the class, for a method or static. */
member: String;
/** A constructor's implicit result: an own of the resource. */
var implicitResult: Ty | null = null;
/** A function the wrapper calls in place of the class's member, when
* the wrapper writes the member itself: a plugin kind's `create`. */
var calleeOverride = "";
new(this.witName, this.base, this.className = "", this.resourceName = "",
this.kind = "", this.member = "");
/** The expression the wrapper calls, before its argument list. */
callee(): String {
if (this.calleeOverride != "") {
return this.calleeOverride;
}
if (this.kind == "constructor") {
return "new " + this.className;
}
if (this.kind == "method") {
return "self0." + this.member;
}
if (this.kind == "static") {
return `${this.className}.${this.member}`;
}
return this.base;
}
/** Whether the wrapper takes the resource's representation first. */
hasSelf(): boolean {
return this.kind == "method";
}
}
/**
* The parameters of an export wrapper, async or sync: the core-shaped
* signature the lift calls with, the statements lifting each into its
* Zena value, and the arguments to call the program's function with.
* A method's `self` leads: the resource's representation, looked up
* in the wrapper's table as `self0`. Throws with the reason on a
* parameter this cannot marshal.
*/
final class WrapperParams {
rawSig = new StringBuilder();
liftStmts = new StringBuilder();
callArgs = new StringBuilder();
}
function renderWrapperParams(target: ExportTarget, func: Func,
items: GrowableArray<InterfaceItem>, uses: SynthUses) {
let witName = target.witName;
let refuse = (what: String, why: String) =>
new Error(`The declared world's export '${witName}', ${what}: ${why}`);
let out = new WrapperParams();
let {rawSig, liftStmts, callArgs} = out;
let selfPrefix = camelName(target.resourceName);
// Every parameter classified and flattened first: past sixteen core
// values in all — a method's `self` among them — the canonical ABI
// spills them into memory and the lift takes one address.
let tys = new GrowableArray<Ty>();
let slotLists = new GrowableArray<GrowableArray<String>>();
var totalFlats = if (target.hasSelf()) 1 else 0;
for (let p in func.params) {
let ty = classifyType(p.type, items);
if (ty.kind == TyKind.Unsupported) {
throw refuse(`parameter '${p.name.name}'`, ty.reason);
}
if (ty.kind == TyKind.ResourceH && ty.isBorrow && !ty.isProgram) {
throw refuse(`parameter '${p.name.name}'`,
"a borrowed handle is the caller's for the call only, and a " +
"wrapper cannot hand it to the program without disposing it " +
"yet");
}
var blocked = liftBlocker(ty, false);
if (blocked == "") { blocked = paramLiftBlocker(ty); }
if (blocked != "") {
throw refuse(`parameter '${p.name.name}'`, blocked);
}
let slots = flatCoreSlots(ty);
if (slots == null) {
throw refuse(`parameter '${p.name.name}'`,
"its variant payloads join across core types, which waits " +
"on the interop stages");
}
tys.push(ty);
slotLists.push(slots as GrowableArray<String>);
totalFlats += (slots as GrowableArray<String>).length;
}
for (var i = 0; i < func.params.length; i += 1) {
if (i > 0) { callArgs.append(", "); }
// A flat scalar is passed as it arrived, unless spilled.
if (tys[i].kind == TyKind.Scalar && totalFlats <= 16) {
callArgs.append("a").append(i32ToString(i));
} else {
callArgs.append("v").append(i32ToString(i));
}
}
if (totalFlats > 16) {
// Spilled: the parameters in memory, back to back at their aligned
// offsets, in a buffer the host allocated through the lift's
// realloc and the guest frees once everything is lifted.
uses.useAbi("freeLifted");
rawSig.append("args: i32");
var offset = 0;
if (target.hasSelf()) {
uses.useAbi("loadI32");
liftStmts.append(` let self0 = ${selfPrefix}At(loadI32(args));\n`);
offset = 4;
}
for (var i = 0; i < tys.length; i += 1) {
let ty = tys[i];
offset = alignTo(offset, ty.align);
let at = if (offset == 0) "args" else "args + " + i32ToString(offset);
liftStmts.append(" let v").append(i32ToString(i)).append(" = ")
.append(liftExprOf(ty, at, uses)).append(";\n");
offset += ty.size;
}
liftStmts.append(" freeLifted(args);\n");
return out;
}
if (target.hasSelf()) {
rawSig.append("self: i32");
liftStmts.append(` let self0 = ${selfPrefix}At(self);\n`);
}
for (var i = 0; i < tys.length; i += 1) {
let ty = tys[i];
let k = i32ToString(i);
let slotTypes = slotLists[i];
if (i > 0 || target.hasSelf()) { rawSig.append(", "); }
if (ty.kind == TyKind.Str) {
// The host lowered the string into linear memory through the
// lift's realloc; the guest owns that buffer and frees it once
// the value is copied out.
uses.useAbi("stringFromMemory");
uses.useAbi("releaseStringArgument");
rawSig.append("p").append(k).append(": i32, l").append(k)
.append(": i32");
liftStmts.append(" let v").append(k).append(" = stringFromMemory(p")
.append(k).append(", l").append(k).append(");\n");
liftStmts.append(" releaseStringArgument(p").append(k)
.append(", l").append(k).append(");\n");
continue;
}
if (ty.kind == TyKind.Scalar) {
// Declared at its own spelling: a scalar's core type is its own.
rawSig.append("a").append(k).append(": ").append(ty.scalar);
continue;
}
// One core value keeps the plain `aK` name; several are `aK_j`.
let names = new GrowableArray<String>();
for (var j = 0; j < slotTypes.length; j += 1) {
let name = if (slotTypes.length == 1) "a" + k
else `a${k}_${i32ToString(j)}`;
names.push(name);
if (j > 0) { rawSig.append(", "); }
rawSig.append(name).append(": ").append(slotTypes[j]);
}
liftStmts.append(" let v").append(k).append(" = ")
.append(liftFlatExpr(ty, slotTypes, names, 0, uses)).append(";\n");
}
return out;
}
/** What `liftBlocker` does not ask: whether an export's parameter
* holds a borrowed handle, which a wrapper cannot hand to the program
* without also owning its disposal. The reason, or the empty string. */
function paramLiftBlocker(ty: Ty): String {
if (ty.kind == TyKind.ResourceH && ty.isBorrow && !ty.isProgram) {
return "a borrowed handle inside an aggregate cannot be lifted yet";
}
for (let child in ty.children) {
let inner = paramLiftBlocker(child);
if (inner != "") { return inner; }
}
return "";
}
/**
* One synchronous export's `<name>_export_sync` wrapper: the lift
* calls it with the WIT's flattened parameters, it calls the program's
* function, and it returns the result the way a synchronous lift
* takes one — the one core value a result flattens to, or, past one,
* the address of a return area holding the result in its canonical
* layout, staged until the host has read it and `post-return` runs.
* Throws with the reason on a parameter or result this cannot marshal.
*/
function renderSyncExportWrapper(sb: StringBuilder, target: ExportTarget,
func: Func, items: GrowableArray<InterfaceItem>, uses: SynthUses): void {
let witName = target.witName;
let base = target.base;
let callee = target.callee();
let refuse = (what: String, why: String) =>
new Error(`The declared world's export '${witName}', ${what}: ${why}`);
// A stream or future is pumped from the task that owns it, by the
// host's callback re-entries — after the value has been returned,
// for a result. A synchronous export has no task and is never
// re-entered, so its pump would park forever on the first copy.
let pumped = "a stream or future is pumped by callback re-entries, " +
"which a synchronous export never gets; declare the export " +
"`async func`";
for (let p in func.params) {
if (carriesEnd(classifyType(p.type, items))) {
throw refuse(`parameter '${p.name.name}'`, pumped);
}
}
if (func.result != null &&
carriesEnd(classifyType(func.result as Type, items))) {
throw refuse("the result", pumped);
}
let params = renderWrapperParams(target, func, items, uses);
let result = func.result;
// A constructor's result is implicit: an own of the resource.
var resultTyOpt = target.implicitResult;
if (resultTyOpt == null && result != null) {
resultTyOpt = classifyType(result as Type, items);
}
if (resultTyOpt == null) {
sb.append("export function ").append(base)
.append(componentSyncExportSuffix).append("(")
.append(params.rawSig.toString()).append("): void {\n");
sb.append(params.liftStmts.toString());
sb.append(" ").append(callee).append("(")
.append(params.callArgs.toString()).append(");\n}\n");
return;
}
let resultTy = resultTyOpt as Ty;
if (resultTy.kind == TyKind.Unsupported) {
throw refuse("the result", resultTy.reason);
}
if (resultTy.kind == TyKind.ResultT) {
for (let child in resultTy.children) {
if (isVoid(child)) { continue; }
let blocked = lowerBlocker(child);
if (blocked != "") { throw refuse("the result", blocked); }
}
} else {
let blocked = lowerBlocker(resultTy);
if (blocked != "") { throw refuse("the result", blocked); }
}
let slotTypes = flatCoreSlots(resultTy) as GrowableArray<String>;
let zenaResult = futurePayloadZenaType(resultTy, uses);
if (slotTypes.length == 1) {
// One core value: returned as the call's result.
sb.append("export function ").append(base)
.append(componentSyncExportSuffix).append("(")
.append(params.rawSig.toString()).append("): ")
.append(slotTypes[0]).append(" {\n");
sb.append(params.liftStmts.toString());
sb.append(" let value = ").append(callee).append("(")
.append(params.callArgs.toString()).append(");\n");
let zero = if (slotTypes[0] == "f32" || slotTypes[0] == "f64") "0.0"
else "0";
sb.append(" var s0: ").append(slotTypes[0]).append(" = ")
.append(zero).append(";\n");
let slotNames = growable<String>(["s0"]);
currentSlotTypes = slotTypes;
lowerFlatStmts(sb, resultTy, "value", slotNames, 0, " ", uses);
sb.append(" return s0;\n}\n");
return;
}
// Past one core value: the canonical layout in a return area. The
// area and everything the value stages inside it (a string's bytes,
// a list's elements) stay allocated until the host has read them
// and calls `post-return`, which releases the staged range.
uses.useAbi("stagedMark");
uses.useAbi("stageBuffer");
uses.useAbi("notePostReturn");
sb.append("export function ").append(base)
.append(componentSyncExportSuffix).append("(")
.append(params.rawSig.toString()).append("): i32 {\n");
sb.append(params.liftStmts.toString());
sb.append(" let value = ").append(callee).append("(")
.append(params.callArgs.toString()).append(");\n");
sb.append(" let m0 = stagedMark();\n");
sb.append(" let ret = stageBuffer(")
.append(i32ToString(resultTy.size)).append(");\n");
emit(sb, " ", lowerMemStmts(resultTy, "value", "ret", uses));
sb.append("\n");
sb.append(" notePostReturn(m0);\n");
sb.append(" return ret;\n}\n");
}
/**
* One async export's typed return and `<name>_export` wrapper. Throws
* with the reason on a parameter or result this cannot marshal.
*/
function renderExportWrapper(sb: StringBuilder, target: ExportTarget,
func: Func, items: GrowableArray<InterfaceItem>, uses: SynthUses,
returnScope: String): void {
let witName = target.witName;
let base = target.base;
let callee = target.callee();
let refuse = (what: String, why: String) =>
new Error("The declared world's async export '" + witName + "', " +
what + ": " + why);
let params = renderWrapperParams(target, func, items, uses);
let {rawSig, liftStmts, callArgs} = params;
let result = func.result;
var hasResult = false;
var resultTy = voidTy();
var zenaResult = "void";
let slotNames = new Array<String>();
var slotTypes = new Array<String>();
if (result != null) {
hasResult = true;
let resultType = result as Type;
resultTy = classifyType(resultType, items);
if (resultTy.kind == TyKind.Unsupported) {
throw refuse("the result", resultTy.reason);
}
if (resultTy.kind == TyKind.ResultT) {
for (let child in resultTy.children) {
if (isVoid(child)) { continue; }
let blocked = lowerBlocker(child);
if (blocked != "") { throw refuse("the result", blocked); }
}
} else {
let blocked = lowerBlocker(resultTy);
if (blocked != "") { throw refuse("the result", blocked); }
}
let slots = flatCoreSlots(resultTy);
if (slots == null) {
throw refuse("the result", "its variant payloads join across " +
"core types, which waits on the interop stages");
}
slotTypes = slots as GrowableArray<String>;
if (slotTypes.length > 16) {
throw refuse("the result", "a result spilling past sixteen core " +
"values waits on the interop stages");
}
zenaResult = futurePayloadZenaType(resultTy, uses);
// The typed return, at the WIT's own spelling of the result: the
// encoder writes the type, and the flat parameters are its
// flattening.
let typeText = spanText(resultType.span.start, resultType.span.end);
sb.append("@external(\"canon\", \"task.return#").append(witName)
.append("\", \"return:").append(returnScope).append("#")
.append(typeText).append("\")\n");
sb.append("declare function taskReturn").append(pascalName(base))
.append("(");
for (var k = 0; k < slotTypes.length; k += 1) {
let slotName = "s" + i32ToString(k);
slotNames.push(slotName);
if (k > 0) { sb.append(", "); }
sb.append(slotName).append(": ").append(slotTypes[k]);
}
sb.append("): void;\n\n");
}
sb.append("export function ").append(base)
.append(componentExportSuffix).append("(").append(rawSig.toString())
.append("): void {\n");
sb.append(liftStmts.toString());
if (!hasResult) {
// Nothing to return, but not before the work is done. An async
// implementation hands its future to the driver, which issues the
// bare `task.return` once it settles: a task whose work pends on a
// waitable another task armed has nothing in its own set, and
// would otherwise exit at its first entry. A synchronous one is
// done when it returns, and the driver's exit returns for it.
let entry = currentEntryAst;
let isAsyncCallee = entry != null && target.kind != "constructor" &&
exportedFunctionIsAsync(entry as Module, target.base, target.className,
target.member);
if (isAsyncCallee) {
sb.append(" finishVoidTask(").append(callee).append("(")
.append(callArgs.toString()).append("));\n}\n");
} else {
sb.append(" ").append(callee).append("(").append(callArgs.toString())
.append(");\n}\n");
}
return;
}
sb.append(" finishTask<").append(zenaResult).append(">(")
.append(callee).append("(").append(callArgs.toString())
.append("), (value: ").append(zenaResult).append("): void => {\n");
let staging = mayStage(resultTy);
if (staging) {
// Staged until the return has consumed them: `task.return` lifts
// its arguments during the call.
uses.useAbi("stagedMark");
uses.useAbi("releaseStagedFrom");
sb.append(" let m0 = stagedMark();\n");
}
for (var k = 0; k < slotNames.length; k += 1) {
let zero = if (slotTypes[k] == "f32" || slotTypes[k] == "f64") "0.0"
else "0";
sb.append(" var ").append(slotNames[k]).append(": ")
.append(slotTypes[k]).append(" = ").append(zero).append(";\n");
}
currentSlotTypes = slotTypes;
lowerFlatStmts(sb, resultTy, "value", slotNames, 0, " ", uses);
sb.append(" taskReturn").append(pascalName(base)).append("(");
for (var k = 0; k < slotNames.length; k += 1) {
if (k > 0) { sb.append(", "); }
sb.append(slotNames[k]);
}
sb.append(");\n");
if (staging) {
sb.append(" releaseStagedFrom(m0);\n");
}
sb.append(" });\n}\n");
}
- zena-lang:wit-parser wit-parser.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|