Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion docs/how/wasm/test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,16 @@ uncaught exception.
wasm64 needs Node 24 or later. LLVM gives a wasm64 module 64-bit tables, which older V8 cannot
instantiate.

## Exceptions

`try`/`catch` and `finally` are wasm exception handling (the `exception-handling` feature, in every
current browser and Node). The tslang compiler's `WasmExceptionPass` turns each landing pad into a
catch of the C++ exception tag, `__cpp_exception`, which the module imports. The host creates the
tag, so instantiate through `host.instantiate(bytes)`, which reads the tag's parameter type from the
module: a pointer, i32 or i64. The host also keeps what a C++ runtime would: `__cxa_throw` throws a
`WebAssembly.Exception` of that tag, and it tracks each exception's type and the exceptions being
handled. A JS exception (`exit()`, a failed assert) is not of that tag, so no `catch` sees it.

## The tests

node run_tests.mjs [--suite=tester,defaultlib] [--triple=wasm32,wasm64] [--mm=none,rc,own] [--debug] [-j<n>] [filter]
Expand All @@ -43,7 +53,6 @@ and every failure are written to `out/results.txt`.

Some tests are skipped, each with its reason:

- tests that catch an exception (`try`/`catch` does not catch on wasm yet; a throw ends the program)
- async tests (the async runtime has no wasm build)
- tests that use threads
- default-library tests marked `// gc only`, `// linux only`, or (under own) `// not own`
Expand Down
121 changes: 112 additions & 9 deletions docs/how/wasm/test/host.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
// tslang's `long`) is an i64 on both and so always a BigInt.
//
// const host = createHost({ args, write, node });
// const { instance } = await WebAssembly.instantiate(bytes, host.imports);
// const instance = await host.instantiate(bytes);
// const exitCode = host.run(instance);

export class ExitSignal extends Error
Expand All @@ -23,7 +23,7 @@ export class ExitSignal extends Error
}
}

// a C++ exception nothing caught: on wasm try/catch does not catch yet, so every throw ends here
// a C++ exception nothing caught: run() turns the WebAssembly.Exception that left main into this
export class UncaughtThrow extends Error
{
constructor(objectAddress)
Expand All @@ -33,6 +33,25 @@ export class UncaughtThrow extends Error
}
}

// Whether a module's memory is a memory64 one (wasm64): the limits flags of its memory section.
// The C++ exception tag the module imports carries a pointer, an i64 there.
export function isMemory64(bytes)
{
const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes.buffer ?? bytes, bytes.byteOffset ?? 0, bytes.byteLength);
let p = 8;
const leb = () => { let r = 0, scale = 1, c; do { c = b[p++]; r += (c & 0x7f) * scale; scale *= 128; } while (c & 0x80); return r; };
while (p < b.length)
{
const id = b[p++];
const size = leb();
const end = p + size;
if (id === 5 && leb() > 0) return (b[p] & 0x04) !== 0;
p = end;
}

return false;
}

const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
const MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];

Expand All @@ -46,6 +65,12 @@ export function createHost(options = {})
let memory;
let is64 = false;

// C++ exceptions (see __cxa_throw): the module's tag, made by instantiate(); each thrown object's
// type_info and handler count; the exceptions being handled, innermost last
let cppExceptionTag;
const exceptions = new Map();
const handled = [];

const N = (v) => Number(v);
const P = (v) => (is64 ? BigInt(v) : v);

Expand Down Expand Up @@ -563,11 +588,18 @@ export function createHost(options = {})
const setResult = (bytes) => { resultBytes = typeof bytes === "string" ? utf8Encoder.encode(bytes) : bytes; return resultBytes.length; };
const fsFail = (e, op, path, dest) =>
{
const code = e?.code ?? "EIO";
const text = (e?.message ?? String(e)).replace(/^[A-Z]+: /, "").replace(/, .*$/, "");
// Node words a few errors of its own (fs.rmSync of a directory: ERR_FS_EISDIR, "Path is a
// directory: rm returned EISDIR (is a directory) ..."): the system error is in them
const nodeError = /^ERR_FS_(E[A-Z]+)$/.exec(e?.code ?? "");
const code = nodeError ? nodeError[1] : (e?.code ?? "EIO");
const text = nodeError
? (/\(([^)]*)\)/.exec(e.message)?.[1] ?? e.message)
: (e?.message ?? String(e)).replace(/^[A-Z]+: /, "").replace(/, .*$/, "");
setResult(`${code}: ${text}, ${op}${path !== undefined ? ` '${path}'` : ""}${dest !== undefined ? ` -> '${dest}'` : ""}`);
return -1;
};
const validEnvName = (name) => name.length > 0 && !name.includes("=");
const invalidEnvName = (op, name) => { setResult(`EINVAL: invalid argument, ${op} '${name}'`); return -1; };
const needNode = (what) => { if (!node) throw new Error(`${what} needs the Node host`); };

let stdinLine = new Uint8Array(0);
Expand Down Expand Up @@ -693,10 +725,59 @@ export function createHost(options = {})
return n;
},

// C++ exceptions: nothing catches them on wasm yet
// C++ exceptions, as a C++ runtime keeps them. A throw is a WebAssembly.Exception of the
// module's __cpp_exception tag carrying the thrown object's address; tslang's catches
// (WasmExceptionPass) catch that tag, ask here for the type_info the object was thrown with,
// and begin and end handling it here.
__cxa_allocate_exception: (size) => P(malloc(size)),
__cxa_free_exception: (p) => free(p),
__cxa_throw: (object) => { throw new UncaughtThrow(N(object)); },
// As libc++abi does it: an exception being handled has a handler count, negative once it
// is rethrown. A catch of the exception already innermost does not stack it again, and the
// last end of a catch destroys it unless it was rethrown, when it lives on to its next catch.
__cxa_throw: (object, type) =>
{
exceptions.set(N(object), { type, handlers: 0 });
throw new WebAssembly.Exception(cppExceptionTag, [object]);
},
__tslang_wasm_exception_type: (object) => exceptions.get(N(object))?.type ?? P(0),
__cxa_begin_catch: (object) =>
{
const exception = exceptions.get(N(object));
if (exception)
{
exception.handlers = Math.abs(exception.handlers) + 1;
if (handled[handled.length - 1] !== N(object)) handled.push(N(object));
}

return object;
},
__cxa_current_exception_type: () => (handled.length ? exceptions.get(handled[handled.length - 1])?.type : undefined) ?? P(0),
__cxa_end_catch: () =>
{
if (!handled.length) return;
const object = handled[handled.length - 1];
const exception = exceptions.get(object);
if (exception.handlers < 0)
{
if (++exception.handlers === 0) handled.pop();
return;
}

if (--exception.handlers === 0)
{
handled.pop();
exceptions.delete(object);
free(object);
}
},
__cxa_rethrow: () =>
{
if (!handled.length) throw new Error("rethrow with no exception being handled");
const object = handled[handled.length - 1];
const exception = exceptions.get(object);
exception.handlers = -exception.handlers;
throw new WebAssembly.Exception(cppExceptionTag, [P(object)]);
},
__assert_fail: (msg, file, line, fn) => { throw new Error(`Assertion failed: ${readStr(msg)}, file ${readStr(file)}, line ${line}`); },
abort: () => { throw new Error("abort()"); },
exit: (code) => { throw new ExitSignal(code); },
Expand Down Expand Up @@ -805,8 +886,19 @@ export function createHost(options = {})
tslang_process_argc: () => args.length,
tslang_process_argv: (i) => (i < 0 || i >= args.length ? -1 : setResult(args[i])),
tslang_process_getenv: (name) => { const v = node?.process.env[readStr(name)]; return v === undefined ? -1 : setResult(v); },
tslang_process_setenv: (name, value) => { if (node) node.process.env[readStr(name)] = readStr(value); return 0; },
tslang_process_unsetenv: (name) => { if (node) delete node.process.env[readStr(name)]; return 0; },
// a name that is empty or has an '=' is EINVAL, as the C++ wrappers say it (setenv's own error)
tslang_process_setenv: (name, value) =>
{
if (!validEnvName(readStr(name))) return invalidEnvName("setenv", readStr(name));
if (node) node.process.env[readStr(name)] = readStr(value);
return 0;
},
tslang_process_unsetenv: (name) =>
{
if (!validEnvName(readStr(name))) return invalidEnvName("unsetenv", readStr(name));
if (node) delete node.process.env[readStr(name)];
return 0;
},
tslang_process_env_count: () => { entries = node ? Object.entries(node.process.env).map(([k, v]) => `${k}=${v}`) : []; return entries.length; },
tslang_process_cwd: () => setResult(node ? node.process.cwd() : "/"),
tslang_process_chdir: (path) => { needNode("process.chdir"); try { node.process.chdir(readStr(path)); return 0; } catch (e) { return fsFail(e, "chdir", readStr(path)); } },
Expand Down Expand Up @@ -898,9 +990,20 @@ export function createHost(options = {})
catch (e)
{
if (e instanceof ExitSignal) return e.code;
if (cppExceptionTag && e instanceof WebAssembly.Exception && e.is(cppExceptionTag)) throw new UncaughtThrow(N(e.getArg(cppExceptionTag, 0)));
throw e;
}
};

return { imports, run, env };
// Instantiates a module with these imports. The C++ exception tag it imports is made here, its
// parameter a pointer: an i32, or an i64 in a memory64 module.
const instantiate = async (bytes) =>
{
cppExceptionTag = new WebAssembly.Tag({ parameters: [isMemory64(bytes) ? "i64" : "i32"] });
env.__cpp_exception = cppExceptionTag;
const { instance } = await WebAssembly.instantiate(bytes, imports);
return instance;
};

return { imports, run, instantiate, env };
}
2 changes: 1 addition & 1 deletion docs/how/wasm/test/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
let status;
try
{
const { instance } = await WebAssembly.instantiateStreaming(fetch(path), host.imports);
const instance = await host.instantiate(await (await fetch(path)).arrayBuffer());
status = `exit code ${host.run(instance)}`;
}
catch (e)
Expand Down
2 changes: 1 addition & 1 deletion docs/how/wasm/test/run.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const host = createHost({
let code;
try
{
const { instance } = await WebAssembly.instantiate(fs.readFileSync(file), host.imports);
const instance = await host.instantiate(fs.readFileSync(file));
code = host.run(instance);
}
catch (e)
Expand Down
4 changes: 1 addition & 3 deletions docs/how/wasm/test/run_tests.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,7 @@
// The tester's tests are the single-file ones its CMakeLists.txt runs (`test-compile-*`): the others
// in the folder are multi-file tests, tests that expect a compile error, or not run at all.
//
// Skipped, and listed as such: tests that catch an exception (try/catch does not catch on wasm yet:
// a throw ends the program), async tests (no async runtime for wasm), threads (none on wasm), the
// Skipped, and listed as such: async tests (no async runtime for wasm), threads (none on wasm), the
// default library's tests marked "// gc only", "// linux only" or (under own) "// not own", and the
// tests in wasm_skips.txt, each with its reason.
//
Expand Down Expand Up @@ -151,7 +150,6 @@ const skipReason = (suite, file, source, leg) =>

const marked = suite.marker?.(source, leg);
if (marked) return marked;
if (/\bcatch\s*[({]/.test(source)) return "catches an exception: try/catch does not catch on wasm yet";
if (/\basync\b|\bawait\b|\bPromise\b/.test(source)) return "async: the async runtime (TypeScriptAsyncRuntime) has no wasm build";
if (/\bThread\.spawn\b|\bnew Worker\b|\bAtomics\.wait\b/.test(source)) return "threads: none on wasm";
return null;
Expand Down
4 changes: 2 additions & 2 deletions docs/how/wasm/test/wasm_skips.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# Tests run_tests.mjs does not run for wasm: `<file> [<triple or model>,...] # <reason>`, every leg
# when none is given. Tests that catch an exception and async tests are skipped without being
# listed here.
# when none is given. Async tests and tests that use threads are skipped without being listed here.

# cannot work on wasm
internals.ts # inline_asm with x86 instructions
Expand All @@ -9,6 +8,7 @@ internals.ts # inline_asm with x86 instructions
00tslang_issue_29_thread.ts # starts threads through _beginthreadex: no threads on wasm
00cppvtable_hidden_return.ts # a @cpp class returning a struct needs the MSVC or a 64-bit Itanium ABI (excluded on i686 too)
fetch.ts # (default library) fetch(): the host has no network, so the request throws
json.ts none # (default library) builds a 100000-character string a character at a time: -mm=none frees none of the ~5 GB, more than a wasm memory holds

# fails natively under the same model too (not run natively under it by ctest)
01tuple.ts own # frees a block it does not own (native own: the program does not finish either)
Expand Down
3 changes: 3 additions & 0 deletions tslang/include/TypeScript/DataStructs.h
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ struct CompileOptions
bool isWindows;
// Bionic has its own assert entry points (__assert/__assert2), not glibc's __assert_fail
bool isAndroid = false;
// wasm32/wasm64 other than Emscripten: try/catch is wasm exception handling (the
// exception-handling feature), its landing pads made funclets by WasmExceptionPass
bool wasmExceptions = false;
bool isExecutable;
bool isDLL;

Expand Down
23 changes: 23 additions & 0 deletions tslang/include/TypeScript/Pass/WasmExceptionPass.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
#ifndef WASMEXCEPTIONPASS__H
#define WASMEXCEPTIONPASS__H

#include "llvm/Pass.h"
#include "llvm/IR/PassManager.h"

namespace ts
{
// wasm32/wasm64 (not Emscripten): turns the Itanium landing pads tslang emits into the funclets
// wasm exception handling is built on. See WasmExceptionPass.cpp.
class WasmExceptionPass : public llvm::PassInfoMixin<WasmExceptionPass>
{
public:
llvm::PreservedAnalyses run(llvm::Module &M, llvm::ModuleAnalysisManager &AM);

static bool isRequired()
{
return true;
}
};
}

#endif // WASMEXCEPTIONPASS__H
1 change: 1 addition & 0 deletions tslang/lib/TypeScriptExceptionPass/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ add_llvm_library(TypeScriptExceptionPass
Win32ExceptionPass.cpp
LandingPadFixPass.cpp
CxxThrowCallingConvPass.cpp
WasmExceptionPass.cpp

ADDITIONAL_HEADER_DIRS

Expand Down
Loading
Loading