From dc8e4602a7e91cf923a91f0d11ffa9f6f061d8a2 Mon Sep 17 00:00:00 2001 From: ASDAlexander77 Date: Mon, 9 Nov 2026 16:52:20 +0000 Subject: [PATCH] README: Worker, step 5 of Worker A Worker entry after Thread: the API as MDN's Worker and DedicatedWorkerGlobalScope, what differs here (a function, not a script URL; self a parameter; receive / dispatch / join instead of an event loop; terminate waits for a running handler), errors to onerror, messages handed over rather than copied, join or terminate every worker, and the two -mm=own limits on handlers. The example prints "squared: 1", "squared: 4", "squared: 9" under gc, rc, none and own. docs/worker-design.md marks step 5 done and the design built. The CI matrix needed no change: tests.ps1 / tests.sh run every test, and CI on main ran the worker tests on Windows and Ubuntu under every model, release and debug. Co-Authored-By: Claude Opus 5.5 --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/worker-design.md | 7 +++++-- 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 24ab893..be63c16 100644 --- a/README.md +++ b/README.md @@ -198,6 +198,44 @@ Generics (`src/generics/lib.generics.ts`): for (const w of workers) w.join(); console.log(Atomics.load(counter.value, 0)); // 4000 ``` +- `Worker`, as MDN's `Worker`: a function on its own thread that talks to the thread that + made it only through messages. `new Worker(body, name?)` runs `body(self)` on a new thread, where + `self` is a `WorkerScope` (MDN's `DedicatedWorkerGlobalScope`: `postMessage`, `onmessage`, + `close()`, `name`); `body` sets `self.onmessage` and returns, and the worker then hands each + message to it until it calls `self.close()`. The worker is a function, not a script URL, and `self` + is its parameter, not a global. On the creating side, `postMessage`, `onmessage` and `onerror` + are as in a browser, with `MessageEvent` (`data`) and `ErrorEvent` (`message`). + There is no event loop to deliver what the worker posts, so the creating thread asks for it: + `receive(timeout?)` takes the next message; `dispatch(timeout?)` hands what has arrived to + `onmessage` / `onerror` and says how many, from the program's own loop; `join()` does so until the + worker has closed, then ends its thread. `terminate()` ends a worker that never closes: what is + queued for it is dropped, it stops once the handler running now returns (it is not interrupted), + and nothing more is delivered from it. Join or terminate every worker. `closed` says whether it + has ended. + What the worker throws reaches `onerror` (none set: it is written to stderr); a throw from a + handler leaves the worker running, a throw from `body` ends it. A message is handed over, not + copied: under `-mm=own` it moves, and elsewhere the sender should not change it afterwards (post + `JSON.stringify(x)` for a copy). + Under `-mm=own` a handler kept in an object can't change a local of the function that set it, so + a creating-side `onmessage` keeps its state in a `Shared` it captures, or the program uses + `receive()`. And once `body` captures anything from the creating thread, the worker's handlers can + use that (through a second handle, `const counter = shared;` inside `body`) or post with `self`, + not both. + + ```ts + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + self.postMessage(`squared: ${e.data * e.data}`); + }; + }); + worker.onerror = (e: ErrorEvent) => console.error(e.message); + for (let i = 1; i <= 3; i++) worker.postMessage(i); + for (let i = 1; i <= 3; i++) { + const reply = worker.receive(); + if (reply != undefined) console.log(reply.data); // squared: 1, squared: 4, squared: 9 + } + worker.terminate(); + ``` - `JSON.stringify(value, null, space)` takes numbers, strings, booleans, `null`, arrays of those, `JsonValue`s, and classes with a `toJSON()`, which can return a `JsonValue` to write out the class's fields. An object literal or a tuple is a `TypeError`, a `BigInt` too. `space` is a number or a diff --git a/docs/worker-design.md b/docs/worker-design.md index ffc66d0..e6577de 100644 --- a/docs/worker-design.md +++ b/docs/worker-design.md @@ -1,6 +1,6 @@ # Worker: design -Date: 2026-11-09. Status: draft for review. +Date: 2026-11-09. Status: built, steps 1-5 (PRs #78, #80-#83, and the README). ## Intent @@ -296,7 +296,10 @@ model; the README example should do the same and name the limit. goes on, a throw from `body` is an error event and the worker ends; `tests/worker_errors.ts`. 4. **Done:** `terminate()`, `dispatch(timeout)`, `MessageQueue.discard()`; `tests/worker_terminate.ts`. -5. README section, next to `Thread`, and the CI matrix picking up the new tests. +5. **Done:** the README section, after `Thread`, with an example checked under all four models + (it prints `squared: 1`, `squared: 4`, `squared: 9`), and the `-mm=own` limits on handlers. The + CI matrix needed no change: `tests.ps1` and `tests.sh` run every file in `tests/`, and CI on + `main` ran the worker tests on Windows and Ubuntu under every model, release and debug. ## Tests (each runs under gc, rc, none and own unless it says otherwise)