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
70 changes: 70 additions & 0 deletions docs/known-issues-worker-ctor-initializer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Known issue: a field initializer crashes a generic class that spawns a thread from its constructor

## Status: open, not fixed; worked around in `Worker`

## Summary

Under `-mm=gc`, `rc` and `none` (release, `tslang` of 2026-11-09), the program below dies with an
access violation (exit code -1073741819) before it prints anything. The class `W` has a field
initializer, `private joined = false`, and its constructor starts a thread from a closure that
captures the constructor's parameters. Move the initializer into the constructor
(`private joined: boolean;` and `this.joined = false;`) and the same program prints `ALL DONE`.
Under `-mm=own` the program doesn't compile, for a different reason: the closure can't take
`body` with it.

Cut-down versions run without crashing: the same shape with a simpler helper in place of
`__worker_run`, or a class that only spawns `body` with the initializer present. So the repro is
the whole program as it was when the crash was found.

## How it was found

The first `Worker` (step 2 of [worker-design.md](worker-design.md)) had this shape. `Worker` now
keeps a `WorkerStart` object and starts its thread with `tslang_thread_spawn`, as `ThreadHandle`
does, which does not hit the crash (checked with `private joined = false` put back).

## Repro

Put it in `tests\`, build the default library for `gc`, and run it as the tests are run
(`tslang --nowarn -mm=gc --opt --opt_level=3 --emit=exe`). It uses `MessageQueue`, `WorkerScope`
and `MessageEvent` from the library.

```ts
function __worker_run<In, Out>(body: (self: WorkerScope<In, Out>) => void, toWorker: Shared<MessageQueue<In>>,
toCreator: Shared<MessageQueue<Out>>, name: string): int {
const scope = new WorkerScope<In, Out>(toCreator, name);
try {
body(scope);
while (!scope.closed) {
const message = toWorker.value.take();
if (message == undefined) {
break;
}
scope.onmessage(new MessageEvent<In>(message));
}
} finally {
toWorker.value.close();
toWorker.value.clear();
toCreator.value.close();
}
return 0;
}
class W<In, Out> {
private a: Shared<MessageQueue<In>>;
private b: Shared<MessageQueue<Out>>;
private t: ThreadHandle<int>;
private joined = false;
constructor(body: (self: WorkerScope<In, Out>) => void, name: string) {
const a = new Shared(new MessageQueue<In>());
const b = new Shared(new MessageQueue<Out>());
this.a = a;
this.b = b;
this.t = Thread.spawn((): int => __worker_run<In, Out>(body, a, b, name));
}
join() { this.t.join(); }
}
function main() {
const h = new W<int, int>((self: WorkerScope<int, int>) => { self.close(); }, "n");
h.join();
print("ALL DONE");
}
```
55 changes: 39 additions & 16 deletions docs/worker-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ worker.join(); // delivers every message until the worker closes, then joins

| Member | Behaviour |
|---|---|
| `constructor(body: (self: WorkerScope<In, Out>) => void)` | Starts the thread (through `Thread.spawn` or the same native entry). |
| `constructor(body: (self: WorkerScope<In, Out>) => void, name?: string)` | Starts the thread through the same native entry `Thread.spawn` uses. `name` is a plain string, not MDN's `{ name }` options object (my call in step 2: the options object had nothing else in it). |
| `postMessage(message: In): void` | Queues the message for the worker. After `terminate()` or after the worker closed, it is dropped silently, as in browsers. |
| `onmessage: (e: MessageEvent<Out>) => void` | Called by `dispatch()` / `join()` for each message from the worker. |
| `onerror: (e: ErrorEvent) => void` | Called the same way for each error the worker reported. With no handler, the error is printed to stderr and dropped (browsers log it to the console). |
Expand All @@ -111,7 +111,7 @@ shapes:
| `postMessage(message: Out): void` | Queues the message for the creator. |
| `onmessage: (e: MessageEvent<In>) => void` | Called by the library's loop for each message. |
| `close(): void` | The loop stops after the handler that called it returns; messages still queued for the worker are dropped. Messages it already posted still reach the creator. |
| `name: string` | From an optional `{ name }` second constructor argument, as MDN's `options.name`. |
| `name: string` | The constructor's optional second argument, as MDN's `options.name`. |

It is passed to `body` as a parameter instead of being the global `self`, because there is one
program-wide global scope here. Naming the parameter `self` keeps ported code reading the same.
Expand All @@ -133,6 +133,8 @@ The constructor spawns a thread whose entry does:
(browsers fail the worker when its script throws at top level).
2. loop: wait for the next message toward the worker, or for a stop request; call
`scope.onmessage(event)` inside a `try`; on a throw, post an error event and continue.
(Until step 3, a throw from `body` or a handler ends the worker instead, and `join()` throws it:
see "Memory models".)
3. leave the loop when `close()` or `terminate()` was called; then mark the worker ended and wake
the creator. (Nothing notices a creator that dropped its `Worker` without ending it: there is no
finalizer to rely on under every model. See "Ending the program".)
Expand Down Expand Up @@ -205,8 +207,30 @@ under the JIT:
- **Both threads reach the queue through a `const` `Shared<MessageQueue<T>>`** each function
captures, under every model, as threads sharing an `Int32Array` do.

Still open for step 2: **a handler that captures a local of the creating thread.** Under `-mm=own` a
closure stored in an object takes what it captures with it, so this is a compile error:
What step 2 (`Worker`, `WorkerScope`, `MessageEvent`; `tests/worker_echo.ts`,
`tests/worker_objects.ts`) settled, the same way:

- **The browser shape works in the worker under every model**, `own` included: `body` sets
`self.onmessage = (e) => { self.postMessage(...); self.close(); }`, a handler capturing `self`.
- **The worker can't start through a closure given to `Thread.spawn` under `own`**: the closure
can't take `body`, a parameter of the `Worker` constructor, with it ("its value is the caller's").
So `Worker` keeps a `WorkerStart` object (the function, both queue handles, the name) and starts
the thread with `tslang_thread_spawn` itself, as `ThreadHandle` does with its `ThreadStart`. The
constructor is `@keeps("body", "name")`.
- **`onmessage` is always a function** (a no-op until set), on both sides, not an optional field:
calling it only when set moves the message on some paths only, which `own` rejects.
- **Until `onerror` exists (step 3), `join()` throws** an `Error` with the message of what the worker
threw, as `ThreadHandle.join` does, and the worker ends. The queues are closed in a `finally`, so
a throw never leaves the creator waiting.
- **A tslang crash** found on the way: the first `Worker` started its thread from a closure in the
constructor; with a field initializer (`private joined = false`) in that class, the program died
with an access violation under `gc`, `rc` and `none`, and assigning the field in the constructor
instead made it run. A cut-down class does not show it, so the repro is the full one:
[known-issues-worker-ctor-initializer.md](known-issues-worker-ctor-initializer.md). The
`WorkerStart` shape does not hit it.

Still open: **a handler on the creating thread that captures a local.** Under `-mm=own` a closure
stored in an object takes what it captures with it, so this is a compile error:

```ts
let total = 0;
Expand All @@ -215,16 +239,19 @@ print(total); // error: 'total' is captured by a closure that escapes, and is
```

The creator's handler has to keep its state somewhere both can reach: a `Shared<T>` it captures, or
a field of an object the handler alone owns, or it can use `receive()` instead of `onmessage`. The
builder should pick the shape the `own` tests and README example use; anything that does not work
goes in the README as a limit, as the `Thread` notes do today.
a field of an object the handler alone owns, or it can use `receive()` instead of `onmessage`.
`tests/worker_echo.ts` collects into a `Shared<T>` the handler captures, which works under every
model; the README example should do the same and name the limit.

## Order of work

1. **Done:** `MessageQueue<T>` (`push`, `take(timeout?)`, `close`, `clear`, `closed`, `length`) in
`lib.generics.ts`, and `tests/message_queue.ts`, where two threads pass 10 000 numbers, strings
and class instances through it in order, under all four models.
2. `Worker` / `WorkerScope` with `postMessage`, `onmessage`, `receive`, `join`, `close`.
2. **Done:** `Worker` / `WorkerScope` / `MessageEvent` with `postMessage`, `onmessage`, `receive`,
`join`, `close`, `closed`, `name`, in `lib.generics.ts`; `tests/worker_echo.ts` (numbers in,
strings out, posting from `body`, `receive` timing out, a handler that throws) and
`tests/worker_objects.ts` (1 000 class instances each way).
3. Errors: `onerror`, throws from `body` and from handlers.
4. `terminate()` and `dispatch(timeout)`.
5. README section, next to `Thread`, and the CI matrix picking up the new tests.
Expand All @@ -251,13 +278,9 @@ see the comment on `Atomics.isLockFree`).

## Left to the builder

- Whether the worker's entry reuses `ThreadHandle` or calls `tslang_thread_spawn` directly.
- Whether `onmessage` / `onerror` are optional fields or fields with no-op defaults (whichever the
compiler handles in a generic class; note the known crash with `cond ? <T>x : undefined` in a
generic class, use `if`/`else`).
- `onerror` should be a no-op-default field like `onmessage` (see step 2 above); note the known
crash with `cond ? <T>x : undefined` in a generic class, use `if`/`else`.
- `MessageQueue.take` takes items out with `shift()`, which is O(n) in what is queued. Fine at
10 000 items; a ring buffer is the change if a worker ever falls far behind.

(`receive` can return `MessageEvent<Out> | undefined` as written: `MessageQueue.take` returns
`T | undefined` and compiles under every model.)
- The `{ name }` option can be dropped if it costs anything.
- (Settled: `receive` returns `MessageEvent<Out> | undefined` as written; `MessageQueue.take`
returns `T | undefined` and compiles under every model.)
164 changes: 163 additions & 1 deletion src/generics/lib.generics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1016,6 +1016,168 @@ class MessageQueue<T> {
}
}

// A message as a handler gets it (MDN's MessageEvent; `origin`, `ports` and `source` are not here)
class MessageEvent<T> {
constructor(public data: T) {}
}

// The worker's side of a Worker (MDN's DedicatedWorkerGlobalScope). The worker's function gets it as
// its parameter, `self` by convention, since a program has one global scope here; a handler that
// captures `self` posts and closes through it, as worker code in a browser does.
class WorkerScope<In, Out> {
// none set: a message is dropped. Always a function, so a message is handed to it on every path,
// which -mm=own needs to know where the message goes.
onmessage: (e: MessageEvent<In>) => void;
private closing: boolean;

constructor(private toCreator: Shared<MessageQueue<Out>>, public name: string) {
this.onmessage = (e: MessageEvent<In>) => {};
this.closing = false;
}

// queues the message for the thread that made the worker
postMessage(message: Out) {
this.toCreator.value.push(message);
}

// ends the worker once the handler running now returns; messages still queued for it are dropped
close() {
this.closing = true;
}

get closed() {
return this.closing;
}
}

// What a worker's thread runs: the function, then each message to onmessage until the worker closes.
// The thread reaches it only through the Opaque handed to the native side, so the Worker keeps it
// until join, as ThreadHandle keeps its ThreadStart. (A closure given to Thread.spawn can't do this
// under -mm=own: it can't take `body`, a parameter of the Worker's constructor, with it.)
class WorkerStart<In, Out> {
failed: boolean;
message: string;

constructor(public body: (self: WorkerScope<In, Out>) => void, public toWorker: Shared<MessageQueue<In>>,
public toCreator: Shared<MessageQueue<Out>>, public name: string) {
this.failed = false;
this.message = "";
}

run() {
// the scope keeps a second handle to the queue, and a string of its own: under -mm=own a
// string kept by a callee is copied by hand (this object keeps its `name` until join)
const scope = new WorkerScope<In, Out>(this.toCreator, this.name + "");
try {
this.body(scope);
while (!scope.closed) {
const message = this.toWorker.value.take();
if (message == undefined) {
break;
}

scope.onmessage(new MessageEvent<In>(message));
}
} catch (e) {
// what the worker threw, for join; reported as an error event once onerror is here
this.failed = true;
this.message = e instanceof Error ? (<Error>e).message : `${e}`;
} finally {
// nothing more reaches the worker, and the creator sees it end
this.toWorker.value.close();
this.toWorker.value.clear();
this.toCreator.value.close();
}
}
}

// the native thread's entry point for a worker: generic, as `sleep` is: see there
function __worker_entry<In, Out>(arg: Opaque): u32 {
const start = <WorkerStart<In, Out>>arg;
start.run();
return 0;
}

// A worker (MDN's Worker): `body` runs on a new thread with the worker's scope, sets its onmessage,
// and returns; the worker then handles each message posted to it until it calls close(). There is no
// event loop to deliver what the worker posts back, so the creating thread asks: receive() takes the
// next message, join() hands each to onmessage until the worker has closed and then ends its thread.
// Join every worker. A message is handed over, not copied: under -mm=own it moves; elsewhere the
// sender should leave it alone. See docs/worker-design.md.
class Worker<In, Out> {
// none set: join() drops what the worker posts. Always a function: see WorkerScope.onmessage.
onmessage: (e: MessageEvent<Out>) => void;
private toWorker: Shared<MessageQueue<In>>;
private toCreator: Shared<MessageQueue<Out>>;
private start: WorkerStart<In, Out>;
private handle: Opaque;
private joined: boolean;

// -mm=own: the worker keeps `body` and `name` until join, so the caller gives them up
@keeps("body", "name")
constructor(body: (self: WorkerScope<In, Out>) => void, name: string = "") {
// each side holds its own handle to both queues: the fields keep one pair, the WorkerStart
// the other
const toWorker = new Shared(new MessageQueue<In>());
const toCreator = new Shared(new MessageQueue<Out>());
this.toWorker = toWorker;
this.toCreator = toCreator;
this.start = new WorkerStart<In, Out>(body, toWorker, toCreator, name);
this.onmessage = (e: MessageEvent<Out>) => {};
this.joined = false;
// -mm=rc: both threads take and drop references to what the worker reaches, so their counts
// change atomically from here on (erased under the other models)
Shared.share(this.start);
this.handle = tslang_thread_spawn(__worker_entry<In, Out>, <Opaque>this.start);
}

// queues the message for the worker; dropped once the worker has closed
postMessage(message: In) {
this.toWorker.value.push(message);
}

// The next message from the worker, without calling onmessage. Waits up to `timeout` milliseconds
// (none: as long as it takes); undefined when the time is up, or once the worker has ended and
// everything it posted has been taken.
receive(timeout?: number): MessageEvent<Out> | undefined {
const message = this.toCreator.value.take(timeout);
if (message == undefined) {
return undefined;
}

return new MessageEvent<Out>(message);
}

// Hands each message from the worker to onmessage until the worker has closed, then ends its
// thread. Throws an Error with the message of what the worker threw, if it threw (onerror is not
// here yet).
join() {
while (true) {
const message = this.toCreator.value.take();
if (message == undefined) {
break;
}

this.onmessage(new MessageEvent<Out>(message));
}

if (!this.joined) {
this.joined = true;
tslang_thread_join(this.handle);
}

// a new Error, as ThreadHandle.join throws: under -mm=own what the worker threw was its own
if (this.start.failed) {
throw new Error(this.start.message);
}
}

// true once the worker has ended and everything it posted has been taken
get closed() {
return this.toCreator.value.closed && this.toCreator.value.length == 0;
}
}

// Bytes to and from the standard streams, as they are: on Windows each call puts its stream in
// binary mode and back, so a "\n" stays one byte and a 0x1A does not end the input (console.log
// and console.readLine keep text mode). A Uint8Array is not a view over a buffer here, so `read`
Expand Down Expand Up @@ -2403,4 +2565,4 @@ class WeakSet<K extends object> {
delete(value: K): boolean {
return this.keys.delete(value);
}
}
}
Loading
Loading