From bf50a7e0a7f65d20359a514a3867ea5ec4fb10ba Mon Sep 17 00:00:00 2001 From: ASDAlexander77 Date: Mon, 9 Nov 2026 16:22:40 +0000 Subject: [PATCH] Worker.terminate() and Worker.dispatch(): step 4 of Worker dispatch(timeout?) hands every message and error that has arrived from the worker to onmessage / onerror and says how many; it waits up to timeout for the first only (none: no wait). It stands in for the event loop in the creating thread's own loop. terminate() ends a worker that never closes, as most browser workers: what was queued for it is dropped, it stops once the running handler returns (not interrupted), its thread ends, and what it posted but was not delivered is dropped. Afterwards onmessage / onerror are not called again, postMessage is ignored, and terminate / join do nothing. MessageQueue.discard() closes a queue and drops what is in it under one lock, so the worker can't take a message in between. Tests: worker_terminate (dispatch then terminate, terminate with 1 000 messages queued, terminate with replies arriving, every call after terminate, terminate an idle and a closed worker). Pass under gc, rc, none and own, release, compiled and under the JIT, after full release builds; debug not built locally. docs/worker-design.md records an -mm=own limit found on the way: once a worker's function captures anything from the creating thread, its handler can use that state (through a second Shared handle) or post with self, not both. Co-Authored-By: Claude Opus 5.5 --- docs/worker-design.md | 37 +++++++++- src/generics/lib.generics.ts | 62 +++++++++++++++-- tests/worker_terminate.ts | 128 +++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+), 10 deletions(-) create mode 100644 tests/worker_terminate.ts diff --git a/docs/worker-design.md b/docs/worker-design.md index fde7127..ffc66d0 100644 --- a/docs/worker-design.md +++ b/docs/worker-design.md @@ -242,6 +242,33 @@ What step 3 (`ErrorEvent`, `onerror`; `tests/worker_errors.ts`) settled, the sam - `receive(timeout)` hands errors to `onerror` on the way to the next message and waits up to `timeout` again after each; the timeout is per wait, not overall. +What step 4 (`terminate()`, `dispatch()`; `tests/worker_terminate.ts`) settled, the same way: + +- **`terminate()` stops the worker by closing its queue, not by a flag**: `MessageQueue.discard()` + closes the queue toward the worker and drops what is in it under one lock, so the worker's next + `take()` gives nothing and its loop ends after the handler running now. Then the thread is joined + and the queue toward the creator is discarded the same way, so nothing it posted is delivered + afterwards and `closed` is true. `postMessage` after it is ignored (the queue is closed), and a + second `terminate()` or a `join()` after it does nothing. +- **`dispatch(timeout?)`** waits up to `timeout` for the first event only (none given: no wait), + then delivers whatever else has already arrived, and returns how many it delivered. +- **Under `own`, sharing state with a worker's handler** (checked on the tslang of 2026-11-09, + 16:05): + - the handler can't capture what the worker's function captured from the creating thread (the + function only lends its captures, and the handler is kept past the call: "borrows a field"); + - taking a second handle inside the function first works: `const counter = handled;` (a + `Shared`), then the handler captures `counter`; + - but **once the worker's function captures anything from the creating thread, a handler that + captures `self` does not compile** ("a closure that escapes owns what it captures, but -mm=own + cannot move this variable into it: its value is the caller's"), whether or not it also captures + `counter`. A worker whose function captures nothing (all of `worker_echo`) is fine. + + So under `own` a worker's handler can use state shared with the creator, or post with `self`, not + both. `worker_terminate` tests each shape on its own. Ways out, none taken yet: give `onmessage` the + scope as a second argument again (step 2 had it), so a handler can post without capturing `self`; + or pass the shared state in a message. The README should name the limit. It looks like a compiler + limit rather than a rule, so it may be worth taking to the compiler repo. + 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: @@ -267,7 +294,8 @@ model; the README example should do the same and name the limit. `tests/worker_objects.ts` (1 000 class instances each way). 3. **Done:** `ErrorEvent`, `Worker.onerror`; a throw from a handler is an error event and the worker goes on, a throw from `body` is an error event and the worker ends; `tests/worker_errors.ts`. -4. `terminate()` and `dispatch(timeout)`. +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. ## Tests (each runs under gc, rc, none and own unless it says otherwise) @@ -276,8 +304,11 @@ model; the README example should do the same and name the limit. - `worker_objects`: a class instance as a message both ways (lists the `own` limit if there is one). - `worker_errors`: a throw from `body`, a throw from a handler (the worker keeps going), a thrown string. (No `onerror` set, printed to stderr, is not in the test: the runner fails on stderr.) -- `worker_terminate`: terminate a waiting worker; terminate while messages are queued (they are - dropped); `postMessage` after terminate is ignored; terminate twice. +- `worker_terminate`: `dispatch()` from the creator's loop, then terminate a worker that never + closes; terminate while 1 000 messages are queued for a slow worker (most are dropped); terminate + while a slow worker's replies are arriving (none is delivered afterwards); `postMessage`, + `dispatch`, `receive`, `join` and `terminate` after terminate; terminate an idle worker and one that + already closed. - `worker_many`: `Thread.hardwareConcurrency()` workers each summing a slice, results gathered with `receive()`. - `worker_gc_collect` (gc only): `GC_gcollect()` while messages are queued; they arrive intact. diff --git a/src/generics/lib.generics.ts b/src/generics/lib.generics.ts index 579673d..7810194 100644 --- a/src/generics/lib.generics.ts +++ b/src/generics/lib.generics.ts @@ -993,6 +993,16 @@ class MessageQueue { this.unlock(); } + // close() and clear() at once: a taker gets nothing more, not even what was queued before + discard() { + this.lock(); + this.sync[2] = 1; + this.items.length = 0; + Atomics.add(this.sync, 1, 1); + this.unlock(); + Atomics.notify(this.sync, 1); + } + get closed() { return Atomics.load(this.sync, 2) != 0; } @@ -1117,10 +1127,11 @@ function __worker_entry(arg: Opaque): u32 { // 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. -// What the worker throws goes to onerror, from either. 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. +// next message, dispatch() hands what has arrived to onmessage, join() does so until the worker has +// closed and then ends its thread. What the worker throws goes to onerror. A worker that never +// closes, as most browser workers, is ended with terminate(). Join or terminate 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; @@ -1194,16 +1205,53 @@ class Worker { } } - if (!this.joined) { - this.joined = true; - tslang_thread_join(this.handle); + this.endThread(); + } + + // Hands each message and error that has arrived from the worker to onmessage / onerror, and says + // how many. With nothing arrived yet, waits up to `timeout` milliseconds for the first (none: does + // not wait). This is the creating thread's event loop, called from its own loop. + dispatch(timeout?: number): int { + let count = 0; + let wait = timeout == undefined ? 0 : timeout; + while (true) { + const post = this.toCreator.value.take(wait); + if (post == undefined) { + return count; + } + + if (post instanceof ErrorEvent) { + this.onerror(post); + } else { + this.onmessage(>post); + } + + count++; + wait = 0; } } + // Ends the worker: what was queued for it is dropped, it stops once the handler running now + // returns (it is not interrupted: a handler that never returns makes this wait for good), its + // thread ends, and what it posted that was not yet delivered is dropped. After this, onmessage and + // onerror are not called again for this worker and postMessage is ignored. Again: does nothing. + terminate() { + this.toWorker.value.discard(); + this.endThread(); + this.toCreator.value.discard(); + } + // 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; } + + private endThread() { + if (!this.joined) { + this.joined = true; + tslang_thread_join(this.handle); + } + } } // Bytes to and from the standard streams, as they are: on Windows each call puts its stream in diff --git a/tests/worker_terminate.ts b/tests/worker_terminate.ts new file mode 100644 index 0000000..81575c0 --- /dev/null +++ b/tests/worker_terminate.ts @@ -0,0 +1,128 @@ +// Worker.terminate() and Worker.dispatch(). Most browser workers never call close(); the creating +// thread takes what they post with dispatch() in its own loop, and ends them with terminate(). +// terminate() stops the worker between handlers (a running handler finishes first), drops what was +// queued for it and what it posted that was not yet delivered, and ends its thread. + +class Log { + lines: string[] = []; + add(line: string) { + this.lines.push(line); + } +} + +// an echo worker that never closes: dispatch() delivers its replies, terminate() ends it +function dispatchThenTerminate() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + self.postMessage(e.data * 2); + }; + }); + + const log = new Shared(new Log()); + worker.onmessage = (e: MessageEvent) => { + log.value.add(`${e.data}`); + }; + + // nothing posted yet: dispatch() without a timeout does not wait + assert(worker.dispatch() == 0, "nothing to deliver yet"); + + worker.postMessage(1); + worker.postMessage(2); + worker.postMessage(3); + + // each dispatch waits up to 100 ms for the first event, then delivers whatever is queued + let delivered = 0; + for (let i = 0; i < 100 && delivered < 3; i++) { + delivered += worker.dispatch(100); + } + + assert(delivered == 3, "three replies delivered"); + assert(log.value.lines.join(",") == "2,4,6", "in order"); + assert(!worker.closed, "the worker is still running"); + + worker.terminate(); + assert(worker.closed, "terminated"); + + // after terminate: postMessage is ignored, nothing is delivered, terminate again does nothing + worker.postMessage(4); + assert(worker.dispatch(20) == 0, "nothing after terminate"); + assert(worker.receive() == undefined, "receive gives nothing after terminate"); + worker.terminate(); + worker.join(); + assert(log.value.lines.length == 3, "onmessage was not called again"); +} + +// terminate while messages are still queued for a slow worker: the rest are dropped. The worker +// counts what it handled in an array the creating thread shares with it. +function terminateDropsQueuedMessages() { + const handled = new Shared(new Int32Array(1)); + const worker = new Worker((self: WorkerScope) => { + // a handle of the worker's own for its handler: under -mm=own the function only lends what it + // captured from the creating thread, and the handler is kept past the call. (Under -mm=own a + // handler of a worker whose function captured something can't also capture `self`, so this + // one doesn't post: see docs/worker-design.md.) + const counter = handled; + self.onmessage = (e: MessageEvent) => { + sleep(1); + Atomics.add(counter.value, 0, 1); + }; + }); + + for (let i = 0; i < 1000; i++) worker.postMessage(i); + worker.terminate(); + + const count = Atomics.load(handled.value, 0); + assert(count < 1000, "the messages still queued were dropped"); + assert(worker.closed, "terminated"); +} + +// terminate while a slow worker's replies are still arriving: none of them is delivered afterwards +function terminateDropsUndeliveredReplies() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + sleep(1); + self.postMessage(e.data); + }; + }); + + for (let i = 0; i < 1000; i++) worker.postMessage(i); + // let some replies arrive, undelivered + sleep(20); + + const log = new Shared(new Log()); + worker.onmessage = (e: MessageEvent) => { + log.value.add(`${e.data}`); + }; + worker.terminate(); + + assert(worker.dispatch() == 0, "the replies not yet delivered were dropped"); + assert(worker.receive(0) == undefined, "receive finds none either"); + assert(log.value.lines.length == 0, "onmessage was never called"); + assert(worker.closed, "terminated"); +} + +// terminate a worker waiting for its first message, and one that already closed itself +function terminateIdleAndClosed() { + const idle = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + self.postMessage(e.data); + }; + }); + idle.terminate(); + assert(idle.closed, "an idle worker ends"); + + const closing = new Worker((self: WorkerScope) => { + self.close(); + }); + closing.join(); + closing.terminate(); + assert(closing.closed, "terminate after join does nothing more"); +} + +function main() { + dispatchThenTerminate(); + terminateDropsQueuedMessages(); + terminateDropsUndeliveredReplies(); + terminateIdleAndClosed(); + print("ALL DONE"); +}