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
37 changes: 34 additions & 3 deletions docs/worker-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<T>`), 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:

Expand All @@ -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)
Expand All @@ -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.
Expand Down
62 changes: 55 additions & 7 deletions src/generics/lib.generics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -993,6 +993,16 @@ class MessageQueue<T> {
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;
}
Expand Down Expand Up @@ -1117,10 +1127,11 @@ function __worker_entry<In, Out>(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<In, Out> {
// none set: join() drops what the worker posts. Always a function: see WorkerScope.onmessage.
onmessage: (e: MessageEvent<Out>) => void;
Expand Down Expand Up @@ -1194,16 +1205,53 @@ class Worker<In, Out> {
}
}

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(<ErrorEvent>post);
} else {
this.onmessage(<MessageEvent<Out>>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
Expand Down
128 changes: 128 additions & 0 deletions tests/worker_terminate.ts
Original file line number Diff line number Diff line change
@@ -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<int, int>((self: WorkerScope<int, int>) => {
self.onmessage = (e: MessageEvent<int>) => {
self.postMessage(e.data * 2);
};
});

const log = new Shared(new Log());
worker.onmessage = (e: MessageEvent<int>) => {
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<int, int>((self: WorkerScope<int, int>) => {
// 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<int>) => {
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<int, int>((self: WorkerScope<int, int>) => {
self.onmessage = (e: MessageEvent<int>) => {
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<int>) => {
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<int, int>((self: WorkerScope<int, int>) => {
self.onmessage = (e: MessageEvent<int>) => {
self.postMessage(e.data);
};
});
idle.terminate();
assert(idle.closed, "an idle worker ends");

const closing = new Worker<int, int>((self: WorkerScope<int, int>) => {
self.close();
});
closing.join();
closing.terminate();
assert(closing.closed, "terminate after join does nothing more");
}

function main() {
dispatchThenTerminate();
terminateDropsQueuedMessages();
terminateDropsUndeliveredReplies();
terminateIdleAndClosed();
print("ALL DONE");
}
Loading