From ec568ea3ea5f22dc9223ebb45f99fc0763c3c07d Mon Sep 17 00:00:00 2001 From: ASDAlexander77 Date: Mon, 9 Nov 2026 13:35:04 +0000 Subject: [PATCH] Worker, WorkerScope and MessageEvent: step 2 of Worker new Worker(body, name?) runs body(self) on a new thread; body sets self.onmessage and the worker then handles each message posted to it until it calls self.close(). With no event loop, the creating thread asks for replies: receive(timeout?) takes the next one, and join() hands each to worker.onmessage until the worker has ended, then ends its thread. Messages go through two MessageQueues, handed over, not copied. - Worker keeps a WorkerStart and starts the thread with tslang_thread_spawn, as ThreadHandle does: under -mm=own a closure given to Thread.spawn can't take the constructor's body with it. - onmessage is always a function (a no-op until set): calling it only when set moves the message on some paths only, which own rejects. - Until onerror (step 3), a throw from body or a handler ends the worker and join() throws an Error with its message; the queues close in a finally, so the creator never waits on a dead worker. Tests: worker_echo (numbers in, strings out, posting from body, receive timing out, a handler that throws) and worker_objects (1 000 class instances each way). Pass under gc, rc, none and own, release, compiled and under the JIT, after full release builds; debug not built locally. docs/known-issues-worker-ctor-initializer.md: a tslang crash found on the way - a field initializer in a generic class whose constructor spawns a thread from a closure dies with an access violation under gc, rc and none. The design doc records what step 2 settled. Co-Authored-By: Claude Opus 5.5 --- docs/known-issues-worker-ctor-initializer.md | 70 ++++++++ docs/worker-design.md | 55 +++++-- src/generics/lib.generics.ts | 164 ++++++++++++++++++- tests/worker_echo.ts | 104 ++++++++++++ tests/worker_objects.ts | 44 +++++ 5 files changed, 420 insertions(+), 17 deletions(-) create mode 100644 docs/known-issues-worker-ctor-initializer.md create mode 100644 tests/worker_echo.ts create mode 100644 tests/worker_objects.ts diff --git a/docs/known-issues-worker-ctor-initializer.md b/docs/known-issues-worker-ctor-initializer.md new file mode 100644 index 0000000..01792db --- /dev/null +++ b/docs/known-issues-worker-ctor-initializer.md @@ -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(body: (self: WorkerScope) => void, toWorker: Shared>, + toCreator: Shared>, name: string): int { + const scope = new WorkerScope(toCreator, name); + try { + body(scope); + while (!scope.closed) { + const message = toWorker.value.take(); + if (message == undefined) { + break; + } + scope.onmessage(new MessageEvent(message)); + } + } finally { + toWorker.value.close(); + toWorker.value.clear(); + toCreator.value.close(); + } + return 0; +} +class W { + private a: Shared>; + private b: Shared>; + private t: ThreadHandle; + private joined = false; + constructor(body: (self: WorkerScope) => void, name: string) { + const a = new Shared(new MessageQueue()); + const b = new Shared(new MessageQueue()); + this.a = a; + this.b = b; + this.t = Thread.spawn((): int => __worker_run(body, a, b, name)); + } + join() { this.t.join(); } +} +function main() { + const h = new W((self: WorkerScope) => { self.close(); }, "n"); + h.join(); + print("ALL DONE"); +} +``` diff --git a/docs/worker-design.md b/docs/worker-design.md index f80c251..c55fe4c 100644 --- a/docs/worker-design.md +++ b/docs/worker-design.md @@ -87,7 +87,7 @@ worker.join(); // delivers every message until the worker closes, then joins | Member | Behaviour | |---|---| -| `constructor(body: (self: WorkerScope) => void)` | Starts the thread (through `Thread.spawn` or the same native entry). | +| `constructor(body: (self: WorkerScope) => 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) => 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). | @@ -111,7 +111,7 @@ shapes: | `postMessage(message: Out): void` | Queues the message for the creator. | | `onmessage: (e: MessageEvent) => 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. @@ -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".) @@ -205,8 +207,30 @@ under the JIT: - **Both threads reach the queue through a `const` `Shared>`** 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; @@ -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` 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` 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` (`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. @@ -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 ? 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 ? 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 | 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 | undefined` as written; `MessageQueue.take` + returns `T | undefined` and compiles under every model.) diff --git a/src/generics/lib.generics.ts b/src/generics/lib.generics.ts index 1b931ff..230dd17 100644 --- a/src/generics/lib.generics.ts +++ b/src/generics/lib.generics.ts @@ -1016,6 +1016,168 @@ class MessageQueue { } } +// A message as a handler gets it (MDN's MessageEvent; `origin`, `ports` and `source` are not here) +class MessageEvent { + 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 { + // 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) => void; + private closing: boolean; + + constructor(private toCreator: Shared>, public name: string) { + this.onmessage = (e: MessageEvent) => {}; + 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 { + failed: boolean; + message: string; + + constructor(public body: (self: WorkerScope) => void, public toWorker: Shared>, + public toCreator: Shared>, 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(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(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 ? (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(arg: Opaque): u32 { + const start = >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 { + // none set: join() drops what the worker posts. Always a function: see WorkerScope.onmessage. + onmessage: (e: MessageEvent) => void; + private toWorker: Shared>; + private toCreator: Shared>; + private start: WorkerStart; + 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) => 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()); + const toCreator = new Shared(new MessageQueue()); + this.toWorker = toWorker; + this.toCreator = toCreator; + this.start = new WorkerStart(body, toWorker, toCreator, name); + this.onmessage = (e: MessageEvent) => {}; + 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, 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 | undefined { + const message = this.toCreator.value.take(timeout); + if (message == undefined) { + return undefined; + } + + return new MessageEvent(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(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` @@ -2403,4 +2565,4 @@ class WeakSet { delete(value: K): boolean { return this.keys.delete(value); } -} \ No newline at end of file +} diff --git a/tests/worker_echo.ts b/tests/worker_echo.ts new file mode 100644 index 0000000..596df50 --- /dev/null +++ b/tests/worker_echo.ts @@ -0,0 +1,104 @@ +// Worker: a function on its own thread that talks to the thread that made it only through messages. +// The worker sets self.onmessage and returns; the library then hands it each message until it calls +// self.close(). The creating thread has no event loop to deliver the replies, so it asks for them: +// receive() takes the next one, and join() hands every one to onmessage until the worker has closed. + +function squares() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + self.postMessage(`squared: ${e.data * e.data}`); + if (e.data == 3) self.close(); + }; + }); + + worker.postMessage(1); + worker.postMessage(2); + worker.postMessage(3); + // after close(): dropped, as in a browser + worker.postMessage(4); + + const first = worker.receive(); + assert(first != undefined && first.data == "squared: 1", "the first reply"); + + // the rest go to onmessage; what it collects lives in a Shared the handler captures, so it is + // still the creator's to read afterwards under -mm=own as well + const replies = new Shared(new Collected()); + worker.onmessage = (e: MessageEvent) => { + replies.value.add(e.data); + }; + worker.join(); + + assert(replies.value.items.length == 2, "two more replies"); + assert(replies.value.items[0] == "squared: 4", "in order"); + assert(replies.value.items[1] == "squared: 9", "in order, to the last"); + assert(worker.closed, "the worker has ended"); + assert(worker.receive() == undefined, "nothing more after the worker ended"); +} + +class Collected { + items: string[] = []; + add(item: string) { + this.items.push(item); + } +} + +// a worker that posts from its body, before any message reaches it, and closes there +function postsFromBody() { + const worker = new Worker((self: WorkerScope) => { + self.postMessage(`hello from ${self.name}`); + self.close(); + }, "greeter"); + + const greeting = worker.receive(); + assert(greeting != undefined && greeting.data == "hello from greeter", "a message posted from the body"); + worker.join(); +} + +// receive with a timeout gives undefined when nothing came in time +function receiveTimesOut() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + if (e.data < 0) { + self.close(); + return; + } + + self.postMessage(e.data + 1); + }; + }); + + assert(worker.receive(20) == undefined, "nothing posted yet"); + worker.postMessage(41); + const answer = worker.receive(); + assert(answer != undefined && answer.data == 42, "the reply"); + worker.postMessage(-1); + worker.join(); +} + +// a worker whose handler throws ends, and join throws an Error with the message (onerror comes later) +function workerThrows() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + throw new Error(`bad message ${e.data}`); + }; + }); + + worker.postMessage(5); + let caught = ""; + try { + worker.join(); + } catch (e: Error) { + caught = e.message; + } + + assert(caught == "bad message 5", "join throws what the worker threw"); + assert(worker.closed, "the worker has ended"); +} + +function main() { + squares(); + postsFromBody(); + receiveTimesOut(); + workerThrows(); + print("ALL DONE"); +} diff --git a/tests/worker_objects.ts b/tests/worker_objects.ts new file mode 100644 index 0000000..f1e49a6 --- /dev/null +++ b/tests/worker_objects.ts @@ -0,0 +1,44 @@ +// Worker with class instances as messages, both ways. A message is handed over, not copied: under +// -mm=own it moves, so the sender can't use it after postMessage. + +class Order { + constructor(public id: int, public items: string[]) {} +} + +class Receipt { + constructor(public id: int, public count: int, public summary: string) {} +} + +function main() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + const order = e.data; + if (order.id < 0) { + self.close(); + return; + } + + self.postMessage(new Receipt(order.id, order.items.length, order.items.join("+"))); + }; + }); + + for (let i = 0; i < 1000; i++) { + const items: string[] = []; + for (let j = 0; j <= i % 3; j++) items.push(`item${j}`); + worker.postMessage(new Order(i, items)); + } + + for (let i = 0; i < 1000; i++) { + const receipt = worker.receive(); + assert(receipt != undefined, "a receipt for every order"); + if (receipt != undefined) { + assert(receipt.data.id == i, "receipts in order"); + assert(receipt.data.count == i % 3 + 1, "the item count"); + assert(receipt.data.summary.startsWith("item0"), "the summary"); + } + } + + worker.postMessage(new Order(-1, [])); + worker.join(); + print("ALL DONE"); +}