/** * The functions the component target synthesizes to sit between the * canonical ABI and the program: the async entry, and one wrapper per * export whose signature carries a string. * * ## The async entry * * A callback-lifted export does not run to completion. It returns a * *code* saying either "done" or "wake me on this waitable set", and the * host re-enters through a callback when something in that set fires. * That is the difference between a timer and a sleep: while the guest * waits, the process is not inside it. * * The two halves live in different places, because they need different * things: * * - The callback is `zena:wasi`'s own `componentResume`, * exported directly. It has to reach the subtask registry and the * microtask queue, which is Zena code, so synthesizing it here would * mean rebuilding in IR what the standard library already says. * - The entry is synthesized here, because it has to call `main`, and * nothing in the standard library can name a program's `main`. * * The entry is two calls: run the program, then ask the driver what to * do next. Everything else — resolving completers, dropping subtasks, * calling `task.return` — is in `component-async.zena`. * * ## The export wrappers * * A component-level `string` is a pointer and a length into linear * memory; a Zena `String` is a view over a garbage-collected byte * array. So `greet(name: String): String` cannot be lifted directly — * the canonical ABI would call it with two `i32`s and expect one back. * The wrapper is the function that has the signature the ABI expects: * it converts each argument, calls the program's function, and converts * the result. * * Both conversions are `zena:wasi`'s, which is Zena, for the * same reason the callback is: allocating and copying is something the * standard library already says, and rebuilding it in `IrBuilder` would * be saying it worse. What is synthesized here is only the shape — * which arguments to convert and in what order — because that is per * export and no source file can name a program's exports. * * A single `string` result is returned indirectly: it flattens to two * core values, one more than a lifted function may return, so the * wrapper returns the address of an 8-byte area holding the pair. That * is `stringResultArea`'s job, and `postReturn` frees it once the * host has read it out. * * See docs/design/component-emission.md, Parts 4 and 5. */ import { WasmModule, WasmFunction, ComponentAsyncExport, ComponentSyncExport, ComponentResourceDtor } from '../wasm-module.zena'; import { ValType, ValTypeI32 } from '../wasm.zena'; import { FunctionDeclaration } from '../../ast.zena'; import { IrBody } from './ir.zena'; import { IrBuilder } from './builder.zena'; import { IrRefFunc } from './ir.zena'; import { isAsyncGeneratorFunction } from './async.zena'; import { ReachabilityAnalysis } from '../reachability/analysis.zena'; import { ExportKey } from '../codegen-utils.zena'; import { componentAbiModule, ComponentValType, componentTypeNeedsMemory, toKebabName } from '../component-emitter.zena'; import { componentTypeOf, declaredTypeOf } from '../component-shape.zena'; import { ClassType, Type, VoidType } from '../../types.zena'; import { isComponentEntryPath, componentEntryRunName, componentExportSuffix, componentSyncExportSuffix, componentExportNameOf } from '../../component-entry.zena'; import { growable } from 'zena:core'; /** Bodies for the synthesized entry, by function uid. */ var entryBodies = new Map(); /** * The stdlib module supplying the driver. It is a path id rather than a * name id because `zena:wasi` is a virtual module: only the * component target resolves it, to this file. */ let driverModule = 'wasi'; /** * Build the async entry, if this program links a driver that needs one. * * "Needs one" is decided by reachability, not by a flag: `componentPoll` * is reached exactly when the program pulled in `zena:wasi` and either * awaited something through it, blocked in `waitable-set.wait` (a stdout * write that did not complete at once — only a task the host lifted * async may block), or has an async main; and always on the zena * command's host. A program that does none of that gets the synchronous * lift and none of this. */ export function prepareComponentEntry( wasm: WasmModule, pass: ReachabilityAnalysis ): void { entryBodies = new Map(); let poll = wasm.getStdlibFunc(driverModule, 'componentPoll'); let resume = wasm.getStdlibFunc(driverModule, 'componentResume'); let begin = wasm.getStdlibFunc(driverModule, 'beginTask'); let markReturned = wasm.getStdlibFunc(driverModule, 'markReturned'); if (poll == null || resume == null || begin == null || markReturned == null) { return; } if (!poll.isReached || !resume.isReached) { // In the function map is not the same as in the module: the // checkable traversal registers functions it only type-walked. // The driver's entry points are reached exactly when reachability // rooted them — when the program awaited an async-lowered import — // and a program that merely links the driver's unit (any // synthesized WIT module does) keeps the synchronous lift. return; } // The callback is one function for every task, whichever export // started it. wasm.componentCallbackFunc = resume; pass.markFunctionReached(resume); pass.markFunctionReached(begin); pass.markFunctionReached(markReturned); let install = hostSetupInstall(wasm, pass); prepareAsyncExports(wasm, pass, begin, install, poll); let key = 'main' as ExportKey; if (!wasm.exportMap.has(key)) { // A service: entered through its exports, with no main to run. The // driver is rooted by the wrapper module a declared world synthesizes, // whether or not any export of it is async, so a component whose // exports are all synchronous arrives here too. There is nothing to // drive in either case; the difference is only that a synchronous one // leaves the driver unused. return; } let main = wasm.exportMap[key]; // `async function main(): Future` is the natural spelling of // a program that awaits, and the entry drives its ramp through // `finishVoidTask` so a rejection lands in `ctx.failure` for // `componentPoll` / `componentResume` to throw. let mainIsAsync = main.isAsyncRamp && !isAsyncGeneratorFunction(main); if (main.signature.params.length != 0) { throw new Error( 'The component target cannot drive a main that takes parameters.' ); } // What the entry calls: `main` itself, or, when an async main's // future carries a value, the wrapper's `run` // (lib/component-entry.zena), which starts main and hands the driver // the typed `task.return` to call once the value is known. A // synchronous main's value is known as soon as it returns, so the // entry returns it itself, through a `task.return` declared here at // the checked return type — an annotation is not needed, and an // enum or a distinct alias returns as the scalar under it. The // lifted entry then has that result type, and the value reaches the // host through the return rather than through the callee. var callee = main; var calleeReturnsFuture = mainIsAsync; var syncReturn: WasmFunction | null = null; wasm.componentEntryResult = -1; if (main.signature.returns.length != 0) { var accepted = false; let declared = declaredTypeOf(main, 'export'); let ret = declared.returnType; if (mainIsAsync) { var payload: Type | null = null; if (ret is ClassType && ret.name == 'Future') { let targs = ret.typeArguments; if (targs != null && targs.length == 1) { payload = targs[0]; } } if (payload != null) { let value = payload as Type; if (value is VoidType) { accepted = true; } else { let result = componentTypeOf(wasm, value); let run = entryWrapperRun(wasm); if (result >= 0 && run != null) { callee = run; calleeReturnsFuture = false; wasm.componentEntryResult = result; pass.markFunctionReached(run); accepted = true; } } } } else { let result = componentTypeOf(wasm, ret); if (result >= 0 && componentTypeNeedsMemory(result)) { // A `string` is read out of linear memory, so its typed return // takes the staged bytes, which the wrapper's `run` stages and // returns; it marks the task returned itself. let run = entryWrapperRun(wasm); if (run != null) { callee = run; wasm.componentEntryResult = result; pass.markFunctionReached(run); accepted = true; } } else if (result >= 0) { wasm.componentEntryResult = result; syncReturn = mainTaskReturn(wasm, main); accepted = true; } } if (!accepted) { throw new Error( 'On this target `main` is lifted async, and an async lift ' + 'returns its result through task.return. Declare it ' + '`main(): void`, `main(): T`, `async function main(): ' + 'Future` or `async function main(): Future`, with T a ' + 'flat scalar or `String`. A `String` result is returned by a ' + 'wrapper chosen from the annotation, so it must be written.' ); } } let entrySig = wasm.getSignature(new Array(0), i32Results()); let entry = new WasmFunction(entrySig, null, main.model); entry.name = 'main$componentRun'; entry.isComponentAdapter = true; wasm.addFunction(entry); pass.markFunctionReached(entry); let b = new IrBuilder(); let block = b.newBlock(); b.switchTo(block); // This call is a task of its own, before anything the program does // can wait or return. b.callFunc(b.addRef(new IrRefFunc(begin)), new Array(0), null); if (install != null) { b.callFunc(b.addRef(new IrRefFunc(install as WasmFunction)), new Array(0), null); } if (calleeReturnsFuture) { let finish = wasm.getStdlibFunc(driverModule, 'finishVoidTask'); if (finish == null) { throw new Error('async main: zena:wasi finishVoidTask was not reached'); } pass.markFunctionReached(finish); let future = b.callFunc(b.addRef(new IrRefFunc(callee)), new Array(0), callee.signature.returns[0]); let args = growable([future]); b.callFunc(b.addRef(new IrRefFunc(finish)), args, finish.signature.returns[0]); } else if (syncReturn != null) { // The value is known now: return it, and tell the driver so it // does not return again at exit. let value = b.callFunc(b.addRef(new IrRefFunc(callee)), new Array(0), callee.signature.returns[0]); let args = growable([value]); b.callFunc(b.addRef(new IrRefFunc(syncReturn as WasmFunction)), args, null); b.callFunc(b.addRef(new IrRefFunc(markReturned)), new Array(0), null); } else { b.callFunc(b.addRef(new IrRefFunc(callee)), new Array(0), null); } let code = b.callFunc(b.addRef(new IrRefFunc(poll)), new Array(0), new ValTypeI32()); b.ret(code); entryBodies[entry.uid] = b.finish(); wasm.componentEntryFunc = entry; } /** * The `task.return#main` import a synchronous main's entry returns * through: a canonical builtin taking main's one core result, added * here because no source module can name a program's main. Its * component-level type is `componentEntryResult`, which the shape * reads for an import with no declaration. */ function mainTaskReturn(wasm: WasmModule, main: WasmFunction): WasmFunction { let params = growable([main.signature.returns[0]]); let sig = wasm.getSignature(params, new Array(0)); let f = new WasmFunction(sig, null, main.model); f.name = 'task.return#main'; f.isImport = true; f.importModule = 'canon'; f.importName = 'task.return#main'; wasm.functionImports.push(f); return f; } /** * `zena:host-setup`'s `installHost`, when the target loads that module * (the zena command's host): called by every entry before the program * runs, so `Error`'s stack traces come from the host. Null on a * portable component, which has no host to ask. */ function hostSetupInstall( wasm: WasmModule, pass: ReachabilityAnalysis ): WasmFunction | null { let install = wasm.getStdlibFunc('host-setup', 'installHost'); if (install != null) { pass.markFunctionReached(install as WasmFunction); } return install; } /** * The `run` of the entry wrapper the compiler loaded beside the entry, * or null when the program has no wrapper. */ function entryWrapperRun(wasm: WasmModule): WasmFunction | null { let prog = wasm.program; if (prog == null) { return null; } for (let unit in prog.units) { if (isComponentEntryPath(unit.ast.path)) { return wasm.getUnitFunc(unit.ast.path, componentEntryRunName); } } return null; } /** * One adapter per async export the entry wrapper implements. The * wrapper's `_export` function takes the export's flattened * core parameters and returns nothing: it starts the program's * function and hands the driver the typed return. The adapter around * it is what the component lifts, with the callback: begin a task, * call the wrapper, then ask the driver what to do next, exactly as * the entry does for main. */ function prepareAsyncExports( wasm: WasmModule, pass: ReachabilityAnalysis, begin: WasmFunction, install: WasmFunction | null, poll: WasmFunction ): void { let prog = wasm.program; if (prog == null) { return; } for (let unit in prog.units) { if (!isComponentEntryPath(unit.ast.path)) { continue; } for (let stmt in unit.ast.body) { if (stmt is FunctionDeclaration) { let name = stmt.name.name; if (!name.endsWith(componentExportSuffix)) { continue; } let found = wasm.getUnitFunc(unit.ast.path, name); if (found == null) { throw new Error('The entry wrapper declares ' + name + ' and codegen registered no function for it.'); } let target = found as WasmFunction; pass.markFunctionReached(target); let exportName = componentExportNameOf(name.sliceBytes(0, name.length - componentExportSuffix.length)); let sig = wasm.getSignature(target.signature.params, i32Results()); let adapter = new WasmFunction(sig, null, target.model); adapter.name = name + '$componentRun'; adapter.isComponentAdapter = true; wasm.addFunction(adapter); pass.markFunctionReached(adapter); let b = new IrBuilder(); let block = b.newBlock(); let args = new Array(); for (let vt in target.signature.params) { args.push(b.blockParam(block, vt)); } b.switchTo(block); b.callFunc(b.addRef(new IrRefFunc(begin)), new Array(0), null); if (install != null) { b.callFunc(b.addRef(new IrRefFunc(install as WasmFunction)), new Array(0), null); } b.callFunc(b.addRef(new IrRefFunc(target)), args, null); let code = b.callFunc(b.addRef(new IrRefFunc(poll)), new Array(0), new ValTypeI32()); b.ret(code); entryBodies[adapter.uid] = b.finish(); wasm.componentAsyncExports.push( new ComponentAsyncExport(exportName, adapter)); } } } } /** * Register the entry wrapper's resource destructors: a * `__dtor` per resource the program provides, which the * component's destructor shim calls when the last handle over an * instance is dropped, from whichever component held it. A core * export, never lifted. */ export function prepareResourceDestructors( wasm: WasmModule, pass: ReachabilityAnalysis ): void { let prog = wasm.program; if (prog == null) { return; } let suffix = '__dtor'; for (let unit in prog.units) { if (!isComponentEntryPath(unit.ast.path)) { continue; } for (let stmt in unit.ast.body) { if (stmt is FunctionDeclaration) { let name = stmt.name.name; if (!name.endsWith(suffix)) { continue; } let found = wasm.getUnitFunc(unit.ast.path, name); if (found == null) { throw new Error('The entry wrapper declares ' + name + ' and codegen registered no function for it.'); } let target = found as WasmFunction; pass.markFunctionReached(target); let resourceName = toKebabName( name.sliceBytes(0, name.length - suffix.length)); wasm.componentResourceDtors.push(new ComponentResourceDtor( resourceName, name + '$dtor', target)); } } } } /** * Register the entry wrapper's synchronous export wrappers — a * `_export_sync` per declared sync export whose types are * richer than a program export lifts on its own. No adapter: the * wrapper's own core signature is the lift's, and the component lifts * it directly, typed from the WIT. Runs whether or not the program * links the async driver: a provider of plain functions has no entry * and never awaits. */ export function prepareSyncExports( wasm: WasmModule, pass: ReachabilityAnalysis ): void { let prog = wasm.program; if (prog == null) { return; } for (let unit in prog.units) { if (!isComponentEntryPath(unit.ast.path)) { continue; } for (let stmt in unit.ast.body) { if (stmt is FunctionDeclaration) { let name = stmt.name.name; if (!name.endsWith(componentSyncExportSuffix)) { continue; } let found = wasm.getUnitFunc(unit.ast.path, name); if (found == null) { throw new Error('The entry wrapper declares ' + name + ' and codegen registered no function for it.'); } let target = found as WasmFunction; pass.markFunctionReached(target); let exportName = componentExportNameOf(name.sliceBytes(0, name.length - componentSyncExportSuffix.length)); wasm.componentSyncExports.push(new ComponentSyncExport( exportName, name + '$componentLift', target)); } } } if (wasm.componentSyncExports.length == 0) { return; } // A result past one core value comes back through a return area the // wrapper stages; `post-return` releases it once the host has read // it, and the lift's memory options name the runtime module's // allocator, both as the string wrappers below arrange. let realloc = wasm.getStdlibFunc(componentAbiModule, 'realloc'); let postReturn = wasm.getStdlibFunc(componentAbiModule, 'postReturn'); if (realloc == null || postReturn == null) { throw new Error('The component target has a wrapped synchronous ' + 'export, and zena:wasi was not linked.'); } pass.markFunctionReached(realloc as WasmFunction); pass.markFunctionReached(postReturn as WasmFunction); wasm.componentReallocFunc = realloc as WasmFunction; wasm.componentPostReturnFunc = postReturn as WasmFunction; } function i32Results(): GrowableArray { let results = growable([new ValTypeI32()]); return results; } /** * Wrap every export whose signature carries a `string`, and pick up the * two core functions the canonical options name. * * Runs whether or not the entry above was built: a program can export * `greet` without ever sleeping. An export of only flat scalars gets no * wrapper and is lifted directly, so a component that moves no strings * is emitted exactly as it was before this existed. */ export function prepareComponentExports( wasm: WasmModule, pass: ReachabilityAnalysis ): void { let fromMemory = wasm.getStdlibFunc(componentAbiModule, 'stringFromMemory'); let release = wasm.getStdlibFunc(componentAbiModule, 'releaseStringArgument'); let resultArea = wasm.getStdlibFunc(componentAbiModule, 'stringResultArea'); let realloc = wasm.getStdlibFunc(componentAbiModule, 'realloc'); let postReturn = wasm.getStdlibFunc(componentAbiModule, 'postReturn'); var wrapped = false; let exportKeys = wasm.exportMap.keys(); for (let key in exportKeys) { let f = wasm.exportMap[key]; let coreName = key as String; if (wasm.componentEntryFunc != null && coreName == 'main') { // Replaced by the async entry, which returns a callback code and // takes nothing. Wrapping it would wrap a function that is not // lifted. continue; } // An export the entry wrapper already marshals, richer than a // string: the component lifts the wrapper, not the function. var bySyncWrapper = false; for (let s in wasm.componentSyncExports) { if (s.exportName == toKebabName(coreName)) { bySyncWrapper = true; } } if (bySyncWrapper) { continue; } let declared = declaredTypeOf(f, 'export'); var carriesString = false; for (let p in declared.parameters) { if (componentTypeOf(wasm, p) == (ComponentValType.String as i32)) { carriesString = true; } } let resultIsString = componentTypeOf(wasm, declared.returnType) == (ComponentValType.String as i32); if (!carriesString && !resultIsString) { continue; } if (fromMemory == null || release == null || resultArea == null || realloc == null || postReturn == null) { throw new Error( "The component target cannot export '" + coreName + "': it carries a string, and zena:wasi was not linked. " + 'That module is one of this target\'s runtime modules and is rooted ' + 'by reachability when a string crosses an export, so this is a ' + 'compiler bug rather than a program error.' ); } if (declared.parameters.length != f.signature.params.length) { // Every export is a top-level function, so the declared parameters // and the core ones line up one for one. A receiver or a captured // environment would break that, and silently wrap the wrong // argument. throw new Error( "The component target cannot export '" + coreName + "': its declaration and its core signature disagree about how " + 'many parameters it takes.' ); } // The core signature the canonical ABI will call: each string // becomes a pointer and a length, everything else stays as the core // module already has it, and a string result becomes the address of // the return area. let params = new Array(); let stringAt = new Array(); for (var i = 0; i < declared.parameters.length; i += 1) { if (componentTypeOf(wasm, declared.parameters[i]) == (ComponentValType.String as i32)) { stringAt.push(true); params.push(new ValTypeI32()); params.push(new ValTypeI32()); } else { stringAt.push(false); params.push(f.signature.params[i]); } } let returns = if (resultIsString) { i32Results() } else { f.signature.returns }; let wrapper = new WasmFunction( wasm.getSignature(params, returns), null, f.model); wrapper.name = coreName + '$componentExport'; wrapper.isComponentAdapter = true; wasm.addFunction(wrapper); pass.markFunctionReached(wrapper); let b = new IrBuilder(); let entry = b.newBlock(); let core = new Array(); for (let vt in params) { core.push(b.blockParam(entry, vt)); } b.switchTo(entry); // Convert each argument, and release the buffer it came in as soon // as it has been copied. The bytes were allocated out of the guest's // own `realloc` when the host lowered them, so they are the guest's // to free, and `post-return` cannot reach them — it is handed the // return area and nothing else. // // Released here rather than after the call so that a program that // throws does not leak them: the wrapper is straight-line, and an // exception leaves it without running anything below. let args = new Array(); var at = 0; for (var i = 0; i < stringAt.length; i += 1) { if (stringAt[i]) { let pair = growable([core[at], core[at + 1]]); args.push(b.callFunc(b.addRef(new IrRefFunc(fromMemory)), pair, f.signature.params[i])); let toRelease = growable([core[at], core[at + 1]]); b.callFunc(b.addRef(new IrRefFunc(release)), toRelease, null); at += 2; } else { args.push(core[at]); at += 1; } } let callResult = if (f.signature.returns.length == 1) { f.signature.returns[0] } else { null }; let called = b.callFunc(b.addRef(new IrRefFunc(f)), args, callResult); if (resultIsString) { let one = growable([called]); b.ret(b.callFunc(b.addRef(new IrRefFunc(resultArea)), one, new ValTypeI32())); } else if (callResult == null) { b.retVoid(); } else { b.ret(called); } entryBodies[wrapper.uid] = b.finish(); wasm.componentExportWrappers[key] = wrapper; wrapped = true; } // Module-wide, not per-export: the canonical options name one // allocator and one post-return however many exports carry a string. if (wrapped) { wasm.componentReallocFunc = realloc as WasmFunction; wasm.componentPostReturnFunc = postReturn as WasmFunction; } } export function lowerComponentAdapter( wasm: WasmModule, func: WasmFunction ): IrBody { if (let (true, body) = entryBodies.get(func.uid)) { return body; } throw new Error('the component entry was not prepared'); }