/** * @file * * The component target's entry wrapper: a module the compiler writes * beside the entry, for the functions whose values reach the host * through a typed `task.return`. * * A callback-lifted export hands its result to the host through * `task.return`, a canonical builtin whose canon entry carries the * result's type. The core function that calls it has to be declared * at that type, and nothing in the standard library can name what a * particular program's functions return. So the declarations are * written here, per program, into a small module loaded beside the * entry. The module imports the program's functions, declares * `task.return` at each one's result type, and exports a wrapper per * function that starts it and hands its future to the driver together * with the typed return to call once the future settles. The entry * adapter (`codegen/ir/component-adapters.zena`) calls a wrapper in * place of the function. * * This file writes the wrapper for `main` when its value needs one: an * async `main` returning a flat scalar or a `String`, and a synchronous * `main` returning a `String`, which the entry cannot return itself * because a `string` result is read out of linear memory. The choice * is made from the entry's syntax alone, the annotation on `main`, so * the wrapper can be loaded in the same compile as the entry, before * anything is checked. A declared world's async exports need the WIT, * which the compiler does not link: `wit-module-synth.zena` writes * those wrappers, with the same shape, and the driver injects it * (`CompilerOptions.componentWrapperSynth`). * * See docs/design/component-async-exports.md. */ import { StringBuilder, join } from 'zena:core'; import { Module, FunctionDeclaration, VariableDeclaration, FunctionExpression, IdentifierPattern, NamedTypeAnnotation, ClassDeclaration, MethodDefinition, Identifier } from './ast.zena'; import { toKebabName } from './codegen/component-emitter.zena'; /** What the wrapper's path adds to the entry's. */ let wrapperSuffix = '.component-entry.zena'; /** Whether `path` names a wrapper this module wrote. */ export function isComponentEntryPath(path: String): boolean { return path.endsWith(wrapperSuffix); } /** The wrapper's path for the entry at `entryPath`. */ export function componentEntryPathFor(entryPath: String): String { return entryPath + wrapperSuffix; } /** The core function name the adapter looks for in the wrapper. */ export let componentEntryRunName = 'run'; /** * What a wrapper adds to a world export's name to name the function * the adapter calls: `describe` is implemented by `describe_export`. * WIT names are kebab-case, so no camelCase rendering of one contains * an underscore and the suffix cannot collide. */ export let componentExportSuffix = '_export'; /** * The component export name a wrapper's base name stands for. A plain * name is the kebab-case of the Zena spelling (`describe`). A * resource's function carries the resource and the kind in the base, * joined by double underscores (no WIT-derived name contains one): * `surface__constructor`, `surface__method__onFrame` and * `surface__static__create` name the canonical ABI's * `[constructor]surface`, `[method]surface.on-frame` and * `[static]surface.create`. The empty string for a base with no * kebab-case rendering. */ export function componentExportNameOf(base: String): String { let parts = base.split('__'); if (parts.length == 1) { return toKebabName(base); } let resource = toKebabName(parts[0]); if (resource == '') { return ''; } if (parts.length == 2 && parts[1] == 'constructor') { return '[constructor]' + resource; } if (parts.length == 3 && (parts[1] == 'method' || parts[1] == 'static')) { let member = toKebabName(parts[2]); if (member == '') { return ''; } return `[${parts[1]}]${resource}.${member}`; } return ''; } /** The wrapper base name for a resource's function: see * `componentExportNameOf`. */ export function resourceWrapperBase(resource: String, kind: String, member: String): String { if (kind == 'constructor') { return resource + '__constructor'; } return `${resource}__${kind}__${member}`; } /** * The suffix of a declared world's synchronous export wrapper — one * whose parameters or result are richer than the flat scalars and * strings a program export lifts on its own. Lifted directly, no * callback: the value comes back from the call, through a return * area when it flattens past one core value. */ export let componentSyncExportSuffix = '_export_sync'; /** * A wrapper to load beside the entry. `entrySpecifier` is how the * wrapper's source imports the entry, and `entryPath` is the loaded * entry's path, which the loader pins that specifier to so the entry * is not loaded a second time under a differently spelled path. */ export final class ComponentEntryWrapper { path: String; source: String; entrySpecifier: String; entryPath: String; new(this.path, this.source, this.entrySpecifier, this.entryPath); } /** * The flat scalar types a `main` may return through the wrapper: * the ones that lift as one core value, and that a synthesized module * can name without importing anything. */ let scalarResults = [ 'bool', 'i8', 'u8', 'i16', 'u16', 'i32', 'u32', 'i64', 'u64', 'f32', 'f64' ]; function isScalarResult(name: String): boolean { for (let s in scalarResults) { if (s == name) { return true; } } return false; } /** * The result `main` returns through the wrapper, as the wrapper spells * its type: a flat scalar's name, `String`, or the empty string when * `main` needs no wrapper. * * An async `main` annotated `Future` needs one for a flat scalar or * a `String` `T`. A synchronous `main` needs one only for `String`: a * scalar is known when it returns, and the entry adapter returns it * itself (ir/component-adapters.zena). */ function wrapperResultOf(func: FunctionExpression) { let annotation = func.returnType; if (!(annotation is NamedTypeAnnotation)) { return ''; } if (!func.isAsync) { return if (isStringResult(annotation)) 'String' else ''; } if (annotation.name == 'Future') { let args = annotation.typeArguments; if (args != null) { if (args.length == 1) { let arg = args[0]; if (arg is NamedTypeAnnotation) { if (isStringResult(arg)) { return 'String'; } if (arg.typeArguments == null) { if (isScalarResult(arg.name)) { return arg.name; } } } } } } return ''; } /** Whether `annotation` is `String`. */ function isStringResult(annotation: NamedTypeAnnotation) { return annotation.name == 'String' && annotation.typeArguments == null; } /** * The result the module's exported `main` returns through the wrapper, * or the empty string: see `wrapperResultOf`. Both spellings count: * `export async function main()` and `export let main = async () => ...`. */ export function mainWrapperResultOf(ast: Module): String { let main = exportedMainOf(ast); return if (main == null) '' else wrapperResultOf(main as FunctionExpression); } /** Whether the module exports an async `main`: the entry the * component lifts on its own, whichever way a declared world spells * it. */ export function hasAsyncMain(ast: Module): boolean { let main = exportedMainOf(ast); return main != null && (main as FunctionExpression).isAsync; } /** * Whether the entry's implementation of an export is `async`: the * function `name` at the top level, in either spelling, or, with * `className`, the method or static `member` of that class. False * when there is no such function, which the compile reports in its * own words. The wrapper for an export that returns nothing asks, to * hand an async implementation's future to the driver and to call a * synchronous one outright. */ export function exportedFunctionIsAsync(ast: Module, name: String, className: String, member: String): boolean { for (let stmt in ast.body) { if (className == '') { if (stmt is FunctionDeclaration) { if (stmt.name.name == name) { return stmt.func.isAsync; } } else if (stmt is VariableDeclaration) { let pattern = stmt.pattern; if (pattern is IdentifierPattern) { if (pattern.name == name) { let init = stmt.init; if (init is FunctionExpression) { return init.isAsync; } } } } } else if (stmt is ClassDeclaration) { if (stmt.name.name == className) { for (let m in stmt.body) { if (m is MethodDefinition) { let mname = m.name; if (mname is Identifier) { if (mname.name == member) { return m.isAsync; } } } } } } } return false; } /** * Whether the entry declares class `className` with a static `member`. * The wrapper for a plugin kind's `create` asks, to write the static * itself when the class leaves it out. */ export function classHasStatic(ast: Module, className: String, member: String): boolean { for (let stmt in ast.body) { if (stmt is ClassDeclaration) { if (stmt.name.name == className) { for (let m in stmt.body) { if (m is MethodDefinition) { let mname = m.name; if (mname is Identifier) { if (mname.name == member && m.isStatic) { return true; } } } } } } } return false; } /** The module's exported `main` function, in either spelling, or * null. */ function exportedMainOf(ast: Module): FunctionExpression | null { for (let stmt in ast.body) { if (stmt is FunctionDeclaration) { if (stmt.exported) { if (stmt.name.name == 'main') { return stmt.func; } } } else if (stmt is VariableDeclaration) { if (stmt.exported) { let pattern = stmt.pattern; if (pattern is IdentifierPattern) { if (pattern.name == 'main') { let init = stmt.init; if (init is FunctionExpression) { return init; } } } } } } return null; } /** The last path segment. */ function baseName(path: String) { var from = 0; for (var i = 0; i < path.length; i += 1) { if (path.getByteAt(i) == 47) { from = i + 1; } // '/' } return path.sliceBytes(from, path.length); } /** How a wrapper beside the entry imports it. */ export function componentEntrySpecifierFor(entryPath: String): String { return './' + baseName(entryPath); } /** The comment every wrapper opens with. */ export function renderWrapperHeader(sb: StringBuilder): void { sb.append('// Written by the compiler for the component target: the '); sb.append('wrappers whose\n'); sb.append('// values reach the host through a typed `task.return`, '); sb.append('declared here at\n'); sb.append('// each one\'s result type and called once its future '); sb.append('settles. See\n'); sb.append('// docs/design/component-async-exports.md.\n'); } /** * The names a main wrapper for `result` imports from `zena:wasi`. * `finishTask` hands an async main's value to the driver; a `String` * is staged into linear memory for the typed return to read, and a * synchronous main's wrapper tells the driver it has returned. */ export function mainWrapperAbiImports(result: String, isAsync: boolean): GrowableArray { let names = new Array(); if (isAsync) { names.push('finishTask'); } if (result == 'String') { names.push('stagedMark'); names.push('stageString'); names.push('releaseStagedFrom'); if (!isAsync) { names.push('markReturned'); } } return names; } /** * The typed return for `main`'s `result`, and `run`, which calls main * and returns its value: through the driver for an async main, once * the future settles, and at once for a synchronous one. Appended to a * wrapper whose imports already bring in `main` and the names * `mainWrapperAbiImports` lists. * * A scalar's `task.return` takes the value. A `String`'s is typed by * the WIT `string`, so its parameters are the staged bytes' address and * length, and the staging is freed once the return has read it. */ export function renderMainWrapper(sb: StringBuilder, result: String, isAsync: boolean): void { let isString = result == 'String'; if (isString) { sb.append('@external("canon", "task.return#main", "return:#string")\n'); sb.append('declare function taskReturnMain(ptr: i32, len: i32): void;\n\n'); sb.append('function returnMain(value: String): void {\n'); sb.append(' let mark = stagedMark();\n'); sb.append(' let (ptr, len) = stageString(value);\n'); sb.append(' taskReturnMain(ptr, len);\n'); sb.append(' releaseStagedFrom(mark);\n'); sb.append('}\n\n'); } else { sb.append('@external("canon", "task.return#main")\n'); sb.append('declare function taskReturnMain(value: ').append(result) .append('): void;\n\n'); } let returnFn = if (isString) 'returnMain' else 'taskReturnMain'; sb.append('export function ').append(componentEntryRunName) .append('(): void {\n'); if (isAsync) { sb.append(' finishTask<').append(result).append('>(main(), (value: ') .append(result).append('): void => {\n'); sb.append(' ').append(returnFn).append('(value);\n'); sb.append(' });\n'); } else { sb.append(' ').append(returnFn).append('(main());\n'); sb.append(' markReturned();\n'); } sb.append('}\n'); } /** * The wrapper for the entry at `entryPath` with syntax `ast`, or null * when the program's `main` is synchronous, returns nothing or * returns something other than a flat scalar. */ export function componentEntryWrapperFor( entryPath: String, ast: Module ): ComponentEntryWrapper | null { let result = mainWrapperResultOf(ast); if (result == '') { return null; } let isAsync = hasAsyncMain(ast); let specifier = componentEntrySpecifierFor(entryPath); let sb = new StringBuilder(); renderWrapperHeader(sb); sb.append('import { main } from \'').append(specifier).append('\';\n'); sb.append('import { '); sb.append(join(mainWrapperAbiImports(result, isAsync), ', ')); sb.append(' } from \'zena:wasi\';\n\n'); renderMainWrapper(sb, result, isAsync); return new ComponentEntryWrapper(componentEntryPathFor(entryPath), sb.toString(), specifier, entryPath); }