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"); +}