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
38 changes: 38 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<In, Out>`, 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<In, Out>` (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<T>` (`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<T>` 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<int, string>((self: WorkerScope<int, string>) => {
self.onmessage = (e: MessageEvent<int>) => {
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
Expand Down
7 changes: 5 additions & 2 deletions docs/worker-design.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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)

Expand Down
Loading