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
25 changes: 23 additions & 2 deletions docs/how/wasm/test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,33 @@ handled. A JS exception (`exit()`, a failed assert) is not of that tag, so no `c
## Async

`async`/`await` and `Promise` lower to MLIR's async runtime (`mlirAsyncRuntime*`). The host
implements it on the program's one thread: an `async` call queues its task, and a blocking
implements it on each thread: an `async` call queues its task, and a blocking
`await` runs queued tasks until what it waits for is ready. `run()` runs the tasks still queued
when `main` returns. `sleep(ms)` blocks: `Atomics.wait` in Node, a busy wait on a browser's main
thread.

## Threads

`Thread.spawn` and `Worker` run under Node. A program that starts a thread (one that calls
`tslang_thread_spawn`) is linked with `--shared-memory --import-memory`: the host makes the shared
memory, and starts each thread in a Node worker ([thread.mjs](thread.mjs)) that instantiates the same
compiled module on it, with a stack and thread-local storage of its own. `join` waits on the
thread's control block with `Atomics.wait`; `Atomics.wait` and `Atomics.notify` work across
threads. A program that starts no thread keeps an unshared memory, so it still runs in a browser
that is not cross-origin isolated.

What this needs from the compiler and the default library:

- Every wasm object is compiled with the `atomics` and `bulk-memory` features, which a shared memory
requires of everything linked into it. Rebuild the default library's wasm archives after updating.
- The heap lives in the module's memory behind a lock, since one thread frees what another allocated.
- On wasm32 a heap block's header is 8 bytes, not 4, so a payload of 64-bit elements is 8-aligned:
a real 64-bit atomic traps on an address that is not.

Not in a browser: a browser does not let its main thread block in `join`, and shares memory only on
a cross-origin-isolated page. Each thread has its own JS host, so what the host keeps (open regular
expression matches, async tasks, C++ exceptions in flight) stays on the thread that made it.

## The tests

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

Some tests are skipped, each with its reason:

- tests that use threads
- default-library tests marked `// gc only`, `// linux only`, or (under own) `// not own`
- the tests in [wasm_skips.txt](wasm_skips.txt)

Expand Down
313 changes: 271 additions & 42 deletions docs/how/wasm/test/host.mjs

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion docs/how/wasm/test/run.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
// uncaught exception. A wasm64 program needs Node's memory64 support, on by default from Node 24
// and behind --experimental-wasm-memory64 before it (run_tests.mjs passes it).
import fs from "node:fs";
import os from "node:os";
import process from "node:process";
import worker_threads from "node:worker_threads";
import { createHost, UncaughtThrow } from "./host.mjs";

const file = process.argv[2];
Expand All @@ -16,7 +18,7 @@ if (!file)

const host = createHost({
args: process.argv.slice(2),
node: { fs, process },
node: { fs, process, worker_threads, os },
write: (fd, text) => fs.writeSync(fd, text),
});

Expand Down
6 changes: 2 additions & 4 deletions docs/how/wasm/test/run_tests.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,8 @@
// 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: 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.
// Skipped, and listed as such: 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.
//
// Under -mm=own, a test that does not compile for wasm is compiled once more for the host
// (--emit=obj): if that fails too, the failure is not wasm's - what -mm=own cannot prove yet - and it
Expand Down Expand Up @@ -150,7 +149,6 @@ const skipReason = (suite, file, source, leg) =>

const marked = suite.marker?.(source, leg);
if (marked) return marked;
if (/\bThread\.spawn\b|\bnew Worker\b|\bAtomics\.wait\b/.test(source)) return "threads: none on wasm";
return null;
};

Expand Down
31 changes: 31 additions & 0 deletions docs/how/wasm/test/thread.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// One thread of a tslang wasm program, in a Node worker: host.mjs's tslang_thread_spawn starts it
// with the program's compiled module, its shared memory and what the thread runs (see runThread).
// The thread writes as the program does, straight to the file descriptors, so its output is not
// held back while the main thread waits in join.
import fs from "node:fs";
import os from "node:os";
import process from "node:process";
import worker_threads from "node:worker_threads";
import { createHost } from "./host.mjs";

const { module, memory, memoryType, args, ...thread } = worker_threads.workerData;

const host = createHost({
args,
node: { fs, process, worker_threads, os },
write: (fd, text) => fs.writeSync(fd, text),
});

try
{
host.runThread(await host.instantiate(module, { memory, memoryType }), thread);
}
catch (e)
{
// the thread did not start (runThread reports what ends a started one): join must still wake
fs.writeSync(2, `${e?.stack ?? e}\n`);
const control = new Int32Array(memory.buffer, thread.control, 3);
control[1] = 2;
Atomics.store(control, 0, 1);
Atomics.notify(control, 0);
}
6 changes: 3 additions & 3 deletions docs/how/wasm/test/wasm_skips.txt
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Tests run_tests.mjs does not run for wasm: `<file> [<triple or model>,...] # <reason>`, every leg
# when none is given. Tests that use threads are skipped without being listed here.
# when none is given.

# cannot work on wasm
internals.ts # inline_asm with x86 instructions
00any_to_opaque_narrow.ts wasm32 # stores a u64 in an Opaque: a pointer is 4 bytes on wasm32
00tslang_issue_29_pthread.ts # starts threads through pthread_create: no threads on wasm
00tslang_issue_29_thread.ts # starts threads through _beginthreadex: no threads on wasm
00tslang_issue_29_pthread.ts # starts threads through pthread_create: the host starts them only through Thread.spawn
00tslang_issue_29_thread.ts # starts threads through _beginthreadex: the host starts them only through Thread.spawn
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
Expand Down
13 changes: 13 additions & 0 deletions tslang/include/TypeScript/DataStructs.h
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,26 @@ struct CompileOptions
{
return static_cast<int>(targetInfo.pointerBits);
}

// The bytes every heap block reserves in front of its payload (Defines.h, HEAP_BLOCK_IMMORTAL):
// one index-sized word, the count - but 8 on wasm32, so that a payload is 8-aligned there. A
// 64-bit atomic (Atomics on a BigInt64Array) traps on an address that is not, and the count, an
// i32, is the first half. A cross-module contract: modules and the default library built with
// a compiler that disagrees on it cannot be linked together.
int heapBlockHeaderBytes() const
{
return isWasm && sizeBits() == 32 ? 8 : sizeBits() / 8;
}
bool isWasm;
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;
// a wasm program (not Emscripten) that starts threads: its memory is imported and shared, which
// the host's workers instantiate the module with (set when the module calls tslang_thread_spawn)
bool wasmThreads = false;
bool isExecutable;
bool isDLL;

Expand Down
6 changes: 3 additions & 3 deletions tslang/include/TypeScript/LowerToLLVM/ArrayLayout.h
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,7 @@ class ArrayLayout : public LLVMCodeHelperBase
mlir::Type globalType = headerType();
if (withWord)
{
globalType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {llvmIndexType, headerType()},
globalType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {getHeapBlockWordType(), headerType()},
/*isPacked=*/true);
}

Expand Down Expand Up @@ -343,8 +343,8 @@ class ArrayLayout : public LLVMCodeHelperBase
globalVal = rewriter.create<LLVM::UndefOp>(loc, globalType);
globalVal = rewriter.create<LLVM::InsertValueOp>(
loc, globalVal,
rewriter.create<LLVM::ConstantOp>(loc, llvmIndexType,
rewriter.getIntegerAttr(llvmIndexType, HEAP_BLOCK_IMMORTAL)),
rewriter.create<LLVM::ConstantOp>(loc, getHeapBlockWordType(),
rewriter.getIntegerAttr(getHeapBlockWordType(), HEAP_BLOCK_IMMORTAL)),
MLIRHelper::getStructIndex(rewriter, 0));
globalVal = rewriter.create<LLVM::InsertValueOp>(loc, globalVal, headerVal,
MLIRHelper::getStructIndex(rewriter, 1));
Expand Down
12 changes: 6 additions & 6 deletions tslang/include/TypeScript/LowerToLLVM/LLVMCodeHelper.h
Original file line number Diff line number Diff line change
Expand Up @@ -367,8 +367,8 @@ class LLVMCodeHelper : public LLVMCodeHelperBase
varName << "td_" << (size_t)hash_value(type) << variant.str() << "_" << name;

TypeConverterHelper tch(typeConverter);
auto llvmIndexType = tch.convertType(th.getIndexType());
auto recordType = TypeDescriptorLogic::getRecordType(rewriter, llvmIndexType);
auto blockWordType = getHeapBlockWordType();
auto recordType = TypeDescriptorLogic::getRecordType(rewriter, blockWordType);
auto nameArrayType = th.getArrayType(th.getI8Type(), name.length() + 1);
auto descriptorType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {recordType, nameArrayType}, false);

Expand Down Expand Up @@ -414,7 +414,7 @@ class LLVMCodeHelper : public LLVMCodeHelperBase
// immortal block header - see TYPE_DESCR_BLOCK_HEADER
setStructValue(loc, recordValue,
rewriter.create<LLVM::ConstantOp>(
loc, llvmIndexType, rewriter.getIntegerAttr(llvmIndexType, HEAP_BLOCK_IMMORTAL)),
loc, blockWordType, rewriter.getIntegerAttr(blockWordType, HEAP_BLOCK_IMMORTAL)),
TYPE_DESCR_BLOCK_HEADER);

mlir::Value descriptorValue = rewriter.create<LLVM::UndefOp>(loc, descriptorType);
Expand Down Expand Up @@ -620,7 +620,7 @@ class LLVMCodeHelper : public LLVMCodeHelperBase
// packed, because the header has to sit exactly one word in front of the data:
// an unpacked struct pads to the data's own alignment, and a vector of three
// i32 wants sixteen bytes, which would put the header two words back instead
auto blockType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {llvmIndexType, dataType},
auto blockType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {getHeapBlockWordType(), dataType},
/*isPacked=*/true);
global = rewriter.create<LLVM::GlobalOp>(loc, blockType, true, LLVM::Linkage::Internal, name, mlir::Attribute{});

Expand All @@ -629,8 +629,8 @@ class LLVMCodeHelper : public LLVMCodeHelperBase
mlir::Value blockVal = rewriter.create<LLVM::UndefOp>(loc, blockType);
blockVal = rewriter.create<LLVM::InsertValueOp>(
loc, blockVal,
rewriter.create<LLVM::ConstantOp>(loc, llvmIndexType,
rewriter.getIntegerAttr(llvmIndexType, HEAP_BLOCK_IMMORTAL)),
rewriter.create<LLVM::ConstantOp>(loc, getHeapBlockWordType(),
rewriter.getIntegerAttr(getHeapBlockWordType(), HEAP_BLOCK_IMMORTAL)),
MLIRHelper::getStructIndex(rewriter, 0));

mlir::Value dataVal = isDense
Expand Down
14 changes: 11 additions & 3 deletions tslang/include/TypeScript/LowerToLLVM/LLVMCodeHelperBase.h
Original file line number Diff line number Diff line change
Expand Up @@ -300,14 +300,15 @@ class LLVMCodeHelperBase
auto llvmIndexType = tch.convertType(th.getIndexType());

// packed: the payload starts right after the header word, where a heap block's does
auto blockType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {llvmIndexType, llvmStorageType},
auto wordType = getHeapBlockWordType();
auto blockType = LLVM::LLVMStructType::getLiteral(rewriter.getContext(), {wordType, llvmStorageType},
/*isPacked=*/true);
auto blockPtr = Alloca(blockType, 1);
// what malloc guarantees a heap block, so the payload's alignment is the same as on the heap
cast<LLVM::AllocaOp>(blockPtr.getDefiningOp()).setAlignment(2 * getHeapBlockHeaderSize());

rewriter.create<LLVM::StoreOp>(
loc, rewriter.create<LLVM::ConstantOp>(loc, llvmIndexType, rewriter.getIntegerAttr(llvmIndexType, HEAP_BLOCK_IMMORTAL)),
loc, rewriter.create<LLVM::ConstantOp>(loc, wordType, rewriter.getIntegerAttr(wordType, HEAP_BLOCK_IMMORTAL)),
blockPtr);
auto payloadPtr = getPayloadPtrFromBlockPtr(loc, blockPtr, llvmIndexType);
rewriter.create<LLVM::StoreOp>(loc, rewriter.create<LLVM::ZeroOp>(loc, llvmStorageType), payloadPtr);
Expand Down Expand Up @@ -338,7 +339,14 @@ class LLVMCodeHelperBase
// moving - sits behind ENABLE_TYPED_GC and was retired in §9.2, before the header existed.
unsigned getHeapBlockHeaderSize()
{
return compileOptions.sizeBits() / 8;
return compileOptions.heapBlockHeaderBytes();
}

// the integer that fills the header in a static block's layout: the count word, padded to the
// header's size (wasm32), all ones for HEAP_BLOCK_IMMORTAL
mlir::Type getHeapBlockWordType()
{
return rewriter.getIntegerType(getHeapBlockHeaderSize() * 8);
}

mlir::Value createHeapBlockHeaderSizeConstant(mlir::Location loc, mlir::Type llvmIndexType, bool negated = false)
Expand Down
16 changes: 8 additions & 8 deletions tslang/include/TypeScript/LowerToLLVM/OwnershipRoutineLogic.h
Original file line number Diff line number Diff line change
Expand Up @@ -1253,14 +1253,14 @@ class OwnershipRoutineLogic
{
TypeHelper th(rewriter);
TypeConverterHelper tch(typeConverter);
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc());
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc(), compileOptions);

auto loc = op->getLoc();

auto recordPtr = tdl.getRecordPtrFromTag(tagValue);
auto releasePtrSlot =
rewriter.create<LLVM::GEPOp>(loc, th.getPtrType(),
TypeDescriptorLogic::getRecordType(rewriter, tch.convertType(th.getIndexType())),
TypeDescriptorLogic::getRecordType(rewriter, rewriter.getIntegerType(compileOptions.heapBlockHeaderBytes() * 8)),
recordPtr, ArrayRef<LLVM::GEPArg>{0, TYPE_DESCR_RELEASE});
auto releaseFn = rewriter.create<LLVM::LoadOp>(loc, th.getPtrType(), releasePtrSlot);

Expand Down Expand Up @@ -1390,7 +1390,7 @@ class OwnershipRoutineLogic
{
TypeHelper th(rewriter);
TypeConverterHelper tch(typeConverter);
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc());
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc(), compileOptions);

auto loc = op->getLoc();
auto ptrTy = th.getPtrType();
Expand All @@ -1399,7 +1399,7 @@ class OwnershipRoutineLogic

auto recordPtr = tdl.getRecordPtrFromTag(tagValue);
auto retainPtrSlot =
rewriter.create<LLVM::GEPOp>(loc, ptrTy, TypeDescriptorLogic::getRecordType(rewriter, tch.convertType(th.getIndexType())),
rewriter.create<LLVM::GEPOp>(loc, ptrTy, TypeDescriptorLogic::getRecordType(rewriter, rewriter.getIntegerType(compileOptions.heapBlockHeaderBytes() * 8)),
recordPtr, ArrayRef<LLVM::GEPArg>{0, TYPE_DESCR_RETAIN});
auto retainFn = rewriter.create<LLVM::LoadOp>(loc, ptrTy, retainPtrSlot);
auto plainRetain = rewriter.create<LLVM::AddressOfOp>(loc, ptrTy, PLAIN_BLOCK_RETAIN_ROUTINE);
Expand Down Expand Up @@ -1824,14 +1824,14 @@ class OwnershipRoutineLogic
{
TypeHelper th(rewriter);
TypeConverterHelper tch(typeConverter);
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc());
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc(), compileOptions);

auto loc = op->getLoc();

auto recordPtr = tdl.getRecordPtrFromTag(tagValue);
auto retainPtrSlot =
rewriter.create<LLVM::GEPOp>(loc, th.getPtrType(),
TypeDescriptorLogic::getRecordType(rewriter, tch.convertType(th.getIndexType())),
TypeDescriptorLogic::getRecordType(rewriter, rewriter.getIntegerType(compileOptions.heapBlockHeaderBytes() * 8)),
recordPtr, ArrayRef<LLVM::GEPArg>{0, TYPE_DESCR_RETAIN});
auto retainFn = rewriter.create<LLVM::LoadOp>(loc, th.getPtrType(), retainPtrSlot);

Expand Down Expand Up @@ -2135,14 +2135,14 @@ class OwnershipRoutineLogic
{
TypeHelper th(rewriter);
TypeConverterHelper tch(typeConverter);
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc());
TypeDescriptorLogic tdl(rewriter, tch, op->getLoc(), compileOptions);

auto loc = op->getLoc();

auto recordPtr = tdl.getRecordPtrFromTag(tagValue);
auto routinePtrSlot =
rewriter.create<LLVM::GEPOp>(loc, th.getPtrType(),
TypeDescriptorLogic::getRecordType(rewriter, tch.convertType(th.getIndexType())),
TypeDescriptorLogic::getRecordType(rewriter, rewriter.getIntegerType(compileOptions.heapBlockHeaderBytes() * 8)),
recordPtr, ArrayRef<LLVM::GEPArg>{0, descriptorSlot});
auto routine = rewriter.create<LLVM::LoadOp>(loc, th.getPtrType(), routinePtrSlot);

Expand Down
15 changes: 9 additions & 6 deletions tslang/include/TypeScript/LowerToLLVM/TypeDescriptorLogic.h
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
#define MLIR_TYPESCRIPT_LOWERTOLLVMLOGIC_TYPEDESCRIPTORLOGIC_H_

#include "TypeScript/Config.h"
#include "TypeScript/DataStructs.h"
#include "TypeScript/Defines.h"
#include "TypeScript/TypeScriptOps.h"

Expand All @@ -25,24 +26,26 @@ class TypeDescriptorLogic
TypeConverterHelper &tch;
TypeHelper th;
Location loc;
const CompileOptions &compileOptions;

public:
TypeDescriptorLogic(PatternRewriter &rewriter, TypeConverterHelper &tch, Location loc)
: rewriter(rewriter), tch(tch), th(rewriter), loc(loc)
TypeDescriptorLogic(PatternRewriter &rewriter, TypeConverterHelper &tch, Location loc, const CompileOptions &compileOptions)
: rewriter(rewriter), tch(tch), th(rewriter), loc(loc), compileOptions(compileOptions)
{
}

// { i32 kind, i32 layout, ptr release, ptr retain, index blockHeader }
static LLVM::LLVMStructType getRecordType(mlir::OpBuilder &builder, mlir::Type llvmIndexType)
// { i32 kind, i32 layout, ptr release, ptr retain, ptr share, blockHeader }: the block header
// an integer of CompileOptions::heapBlockHeaderBytes, the index width but 8 bytes on wasm32
static LLVM::LLVMStructType getRecordType(mlir::OpBuilder &builder, mlir::Type blockWordType)
{
auto i32Ty = builder.getI32Type();
auto ptrTy = LLVM::LLVMPointerType::get(builder.getContext());
return LLVM::LLVMStructType::getLiteral(builder.getContext(), {i32Ty, i32Ty, ptrTy, ptrTy, ptrTy, llvmIndexType}, false);
return LLVM::LLVMStructType::getLiteral(builder.getContext(), {i32Ty, i32Ty, ptrTy, ptrTy, ptrTy, blockWordType}, false);
}

LLVM::LLVMStructType getRecordType()
{
return getRecordType(rewriter, tch.convertType(th.getIndexType()));
return getRecordType(rewriter, rewriter.getIntegerType(compileOptions.heapBlockHeaderBytes() * 8));
}

// Size of the record, and therefore the distance from a tag back to it. The name is a
Expand Down
Loading
Loading