diff --git a/docs/worker-design.md b/docs/worker-design.md index c55fe4c..fde7127 100644 --- a/docs/worker-design.md +++ b/docs/worker-design.md @@ -133,8 +133,6 @@ The constructor spawns a thread whose entry does: (browsers fail the worker when its script throws at top level). 2. loop: wait for the next message toward the worker, or for a stop request; call `scope.onmessage(event)` inside a `try`; on a throw, post an error event and continue. - (Until step 3, a throw from `body` or a handler ends the worker instead, and `join()` throws it: - see "Memory models".) 3. leave the loop when `close()` or `terminate()` was called; then mark the worker ended and wake the creator. (Nothing notices a creator that dropped its `Worker` without ending it: there is no finalizer to rely on under every model. See "Ending the program".) @@ -219,9 +217,8 @@ What step 2 (`Worker`, `WorkerScope`, `MessageEvent`; `tests/worker_echo.ts`, constructor is `@keeps("body", "name")`. - **`onmessage` is always a function** (a no-op until set), on both sides, not an optional field: calling it only when set moves the message on some paths only, which `own` rejects. -- **Until `onerror` exists (step 3), `join()` throws** an `Error` with the message of what the worker - threw, as `ThreadHandle.join` does, and the worker ends. The queues are closed in a `finally`, so - a throw never leaves the creator waiting. +- **(Step 2 only, replaced by step 3:)** a throw ended the worker and `join()` threw it. The queues + are closed in a `finally`, so a throw never leaves the creator waiting; that part stays. - **A tslang crash** found on the way: the first `Worker` started its thread from a closure in the constructor; with a field initializer (`private joined = false`) in that class, the program died with an access violation under `gc`, `rc` and `none`, and assigning the field in the constructor @@ -229,6 +226,22 @@ What step 2 (`Worker`, `WorkerScope`, `MessageEvent`; `tests/worker_echo.ts`, [known-issues-worker-ctor-initializer.md](known-issues-worker-ctor-initializer.md). The `WorkerStart` shape does not hit it. +What step 3 (`ErrorEvent`, `onerror`; `tests/worker_errors.ts`) settled, the same way: + +- **One queue toward the creator carries both kinds of event**, as the event objects themselves: + `MessageQueue | ErrorEvent>` (`type WorkerPost`). Errors arrive in order + with the messages, and `join()` / `receive()` tell them apart with `instanceof ErrorEvent`. +- **An envelope with a `data: T | undefined` field does not work under `own`**: the message can't be + moved out of the field (a plain move is "borrows a field"; a destructuring swap works for a string + but not for a class instance). Queueing the events themselves moves nothing out of a field. +- **What is thrown becomes text**: an `Error`'s `message`, or anything else as `${e}`. Under `own` + the text is borrowed from the thrown object, so `WorkerScope.postError` copies it. +- **The default `onerror` writes `Worker error: ` to stderr** with `console.error`. The + test runner counts any stderr as a failure, so `worker_errors` sets `onerror` everywhere. +- `ErrorEvent` is in `src/core/core.ts` and `core.d.ts`, next to `SyntaxError`. +- `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. + 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: @@ -252,7 +265,8 @@ model; the README example should do the same and name the limit. `join`, `close`, `closed`, `name`, in `lib.generics.ts`; `tests/worker_echo.ts` (numbers in, strings out, posting from `body`, `receive` timing out, a handler that throws) and `tests/worker_objects.ts` (1 000 class instances each way). -3. Errors: `onerror`, throws from `body` and from handlers. +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)`. 5. README section, next to `Thread`, and the CI matrix picking up the new tests. @@ -260,8 +274,8 @@ model; the README example should do the same and name the limit. - `worker_echo`: the example above; numbers in, strings out, order kept, `close()` from inside. - `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), no - `onerror` set (printed to stderr). +- `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_many`: `Thread.hardwareConcurrency()` workers each summing a slice, results gathered with @@ -271,15 +285,12 @@ model; the README example should do the same and name the limit. ## Where the code goes `Worker`, `WorkerScope`, `MessageEvent` and the queue are generic and go in -`src/generics/lib.generics.ts` next to `Thread`. `ErrorEvent` is not generic, so it goes in -`src/lib.ts` with the other non-generic classes (`JsonValue`, `Response`), or in `src/core/core.ts` -next to `Error` (every class and namespace function in `lib.generics.ts` carries a type parameter; -see the comment on `Atomics.isLockFree`). +`src/generics/lib.generics.ts` next to `Thread`. `ErrorEvent` is not generic, so it is in +`src/core/core.ts` next to `Error`, declared in `core.d.ts` (every class and namespace function in +`lib.generics.ts` carries a type parameter; see the comment on `Atomics.isLockFree`). ## Left to the builder -- `onerror` should be a no-op-default field like `onmessage` (see step 2 above); note the known - crash with `cond ? x : undefined` in a generic class, use `if`/`else`. - `MessageQueue.take` takes items out with `shift()`, which is O(n) in what is queued. Fine at 10 000 items; a ring buffer is the change if a worker ever falls far behind. - (Settled: `receive` returns `MessageEvent | undefined` as written; `MessageQueue.take` diff --git a/src/core/core.d.ts b/src/core/core.d.ts index 8c16c12..2abcebe 100644 --- a/src/core/core.d.ts +++ b/src/core/core.d.ts @@ -17,6 +17,11 @@ declare class SyntaxError extends Error { constructor(message?: string, filename?: string, line?: int); } +declare class ErrorEvent { + public message: string; + constructor(message: string); +} + declare namespace PrimeHelpers { declare const hashPrime: int; diff --git a/src/core/core.ts b/src/core/core.ts index 4875239..247a5a4 100644 --- a/src/core/core.ts +++ b/src/core/core.ts @@ -23,6 +23,13 @@ export class SyntaxError extends Error { } } +// What a worker threw, as the thread that made it is told (MDN's ErrorEvent; `filename`, `lineno` +// and `colno` are not here). Made from the message alone: the thrown object was the worker's. +export class ErrorEvent { + public constructor(public message: string) { + } +} + export namespace PrimeHelpers { export const hashPrime = 101; diff --git a/src/generics/lib.generics.ts b/src/generics/lib.generics.ts index 230dd17..579673d 100644 --- a/src/generics/lib.generics.ts +++ b/src/generics/lib.generics.ts @@ -1021,6 +1021,11 @@ class MessageEvent { constructor(public data: T) {} } +// What a worker posts toward the thread that made it: a message, or an error for something it threw. +// One queue carries both, as the events themselves, so errors arrive in order with the messages and +// each is taken out whole (under -mm=own nothing has to move out of a field). +type WorkerPost = MessageEvent | ErrorEvent; + // The worker's side of a Worker (MDN's DedicatedWorkerGlobalScope). The worker's function gets it as // its parameter, `self` by convention, since a program has one global scope here; a handler that // captures `self` posts and closes through it, as worker code in a browser does. @@ -1030,14 +1035,14 @@ class WorkerScope { onmessage: (e: MessageEvent) => void; private closing: boolean; - constructor(private toCreator: Shared>, public name: string) { + constructor(private toCreator: Shared>>, public name: string) { this.onmessage = (e: MessageEvent) => {}; this.closing = false; } // queues the message for the thread that made the worker postMessage(message: Out) { - this.toCreator.value.push(message); + this.toCreator.value.push(new MessageEvent(message)); } // ends the worker once the handler running now returns; messages still queued for it are dropped @@ -1048,40 +1053,51 @@ class WorkerScope { get closed() { return this.closing; } + + // queues an error event for the thread that made the worker. A copy of the text: under -mm=own the + // caller's text is borrowed from what was thrown. + postError(text: string) { + this.toCreator.value.push(new ErrorEvent(text + "")); + } } // What a worker's thread runs: the function, then each message to onmessage until the worker closes. // The thread reaches it only through the Opaque handed to the native side, so the Worker keeps it // until join, as ThreadHandle keeps its ThreadStart. (A closure given to Thread.spawn can't do this // under -mm=own: it can't take `body`, a parameter of the Worker's constructor, with it.) +// +// What the worker throws becomes an error event, as in a browser: a throw from a handler, and the +// worker goes on to the next message; a throw from `body`, and the worker ends. The event carries +// the text alone: under -mm=own the thrown object is the worker's. class WorkerStart { - failed: boolean; - message: string; - constructor(public body: (self: WorkerScope) => void, public toWorker: Shared>, - public toCreator: Shared>, public name: string) { - this.failed = false; - this.message = ""; - } + public toCreator: Shared>>, public name: string) {} run() { // the scope keeps a second handle to the queue, and a string of its own: under -mm=own a // string kept by a callee is copied by hand (this object keeps its `name` until join) const scope = new WorkerScope(this.toCreator, this.name + ""); try { - this.body(scope); - while (!scope.closed) { + let started = true; + try { + this.body(scope); + } catch (e) { + scope.postError(e instanceof Error ? `${(e).message}` : `${e}`); + started = false; + } + + while (started && !scope.closed) { const message = this.toWorker.value.take(); if (message == undefined) { break; } - scope.onmessage(new MessageEvent(message)); + try { + scope.onmessage(new MessageEvent(message)); + } catch (e) { + scope.postError(e instanceof Error ? `${(e).message}` : `${e}`); + } } - } catch (e) { - // what the worker threw, for join; reported as an error event once onerror is here - this.failed = true; - this.message = e instanceof Error ? (e).message : `${e}`; } finally { // nothing more reaches the worker, and the creator sees it end this.toWorker.value.close(); @@ -1102,13 +1118,16 @@ function __worker_entry(arg: Opaque): u32 { // 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. -// 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. +// 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. class Worker { // none set: join() drops what the worker posts. Always a function: see WorkerScope.onmessage. onmessage: (e: MessageEvent) => void; + // none set: the error is printed to stderr, as a browser logs it to the console + onerror: (e: ErrorEvent) => void; private toWorker: Shared>; - private toCreator: Shared>; + private toCreator: Shared>>; private start: WorkerStart; private handle: Opaque; private joined: boolean; @@ -1119,11 +1138,14 @@ class Worker { // each side holds its own handle to both queues: the fields keep one pair, the WorkerStart // the other const toWorker = new Shared(new MessageQueue()); - const toCreator = new Shared(new MessageQueue()); + const toCreator = new Shared(new MessageQueue>()); this.toWorker = toWorker; this.toCreator = toCreator; this.start = new WorkerStart(body, toWorker, toCreator, name); this.onmessage = (e: MessageEvent) => {}; + this.onerror = (e: ErrorEvent) => { + console.error(`Worker error: ${e.message}`); + }; this.joined = false; // -mm=rc: both threads take and drop references to what the worker reaches, so their counts // change atomically from here on (erased under the other models) @@ -1136,40 +1158,46 @@ class Worker { this.toWorker.value.push(message); } - // The next message from the worker, without calling onmessage. Waits up to `timeout` milliseconds - // (none: as long as it takes); undefined when the time is up, or once the worker has ended and - // everything it posted has been taken. + // The next message from the worker, without calling onmessage; an error the worker reported on + // the way is handed to onerror. Waits up to `timeout` milliseconds for each (none: as long as it + // takes); undefined when the time is up, or once the worker has ended and everything it posted has + // been taken. receive(timeout?: number): MessageEvent | undefined { - const message = this.toCreator.value.take(timeout); - if (message == undefined) { - return undefined; - } + while (true) { + const post = this.toCreator.value.take(timeout); + if (post == undefined) { + return undefined; + } - return new MessageEvent(message); + if (post instanceof ErrorEvent) { + this.onerror(post); + continue; + } + + return >post; + } } - // Hands each message from the worker to onmessage until the worker has closed, then ends its - // thread. Throws an Error with the message of what the worker threw, if it threw (onerror is not - // here yet). + // hands each message from the worker to onmessage, and each error to onerror, until the worker has + // closed; then ends its thread join() { while (true) { - const message = this.toCreator.value.take(); - if (message == undefined) { + const post = this.toCreator.value.take(); + if (post == undefined) { break; } - this.onmessage(new MessageEvent(message)); + if (post instanceof ErrorEvent) { + this.onerror(post); + } else { + this.onmessage(>post); + } } if (!this.joined) { this.joined = true; tslang_thread_join(this.handle); } - - // a new Error, as ThreadHandle.join throws: under -mm=own what the worker threw was its own - if (this.start.failed) { - throw new Error(this.start.message); - } } // true once the worker has ended and everything it posted has been taken diff --git a/tests/worker_echo.ts b/tests/worker_echo.ts index 596df50..8489b62 100644 --- a/tests/worker_echo.ts +++ b/tests/worker_echo.ts @@ -75,30 +75,9 @@ function receiveTimesOut() { worker.join(); } -// a worker whose handler throws ends, and join throws an Error with the message (onerror comes later) -function workerThrows() { - const worker = new Worker((self: WorkerScope) => { - self.onmessage = (e: MessageEvent) => { - throw new Error(`bad message ${e.data}`); - }; - }); - - worker.postMessage(5); - let caught = ""; - try { - worker.join(); - } catch (e: Error) { - caught = e.message; - } - - assert(caught == "bad message 5", "join throws what the worker threw"); - assert(worker.closed, "the worker has ended"); -} - function main() { squares(); postsFromBody(); receiveTimesOut(); - workerThrows(); print("ALL DONE"); } diff --git a/tests/worker_errors.ts b/tests/worker_errors.ts new file mode 100644 index 0000000..da1cfd2 --- /dev/null +++ b/tests/worker_errors.ts @@ -0,0 +1,100 @@ +// Worker errors: what a worker throws reaches the creating thread as an ErrorEvent, given to +// worker.onerror by join() and receive(). A throw from a handler leaves the worker running, as in a +// browser; a throw from the worker's function ends the worker. (With no onerror set, the error is +// printed to stderr, which the test runner counts as a failure, so it is not exercised here.) + +class Log { + lines: string[] = []; + add(line: string) { + this.lines.push(line); + } +} + +// a handler that throws on some messages: each throw is an error event, in order with the replies, +// and the worker goes on to the next message +function handlerThrows() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + if (e.data < 0) { + self.close(); + return; + } + + if (e.data % 2 == 1) { + throw new RangeError(`odd: ${e.data}`); + } + + self.postMessage(e.data * 10); + }; + }); + + for (let i = 0; i < 6; i++) worker.postMessage(i); + worker.postMessage(-1); + + const log = new Shared(new Log()); + worker.onmessage = (e: MessageEvent) => { + log.value.add(`message ${e.data}`); + }; + worker.onerror = (e: ErrorEvent) => { + log.value.add(`error ${e.message}`); + }; + worker.join(); + + const lines = log.value.lines; + assert(lines.length == 6, "three replies and three errors"); + assert(lines[0] == "message 0", "in order"); + assert(lines[1] == "error odd: 1", "the error between the replies"); + assert(lines[2] == "message 20", "the worker went on"); + assert(lines[3] == "error odd: 3", "a second error"); + assert(lines[4] == "message 40", "and on"); + assert(lines[5] == "error odd: 5", "the last error"); + assert(worker.closed, "the worker has ended"); +} + +// the worker's function throws: an error event, and the worker ends +function bodyThrows() { + const worker = new Worker((self: WorkerScope) => { + self.postMessage(1); + throw new Error("setup failed"); + }); + + const log = new Shared(new Log()); + worker.onerror = (e: ErrorEvent) => { + log.value.add(e.message); + }; + + // receive gives the message, then hands the error to onerror and finds the worker ended + const first = worker.receive(); + assert(first != undefined && first.data == 1, "what was posted before the throw"); + assert(worker.receive() == undefined, "nothing more: the worker ended"); + assert(log.value.lines.length == 1 && log.value.lines[0] == "setup failed", "onerror got the error"); + + // join does not throw: the error was reported + worker.join(); + assert(worker.closed, "the worker has ended"); +} + +// something thrown that is not an Error still reaches onerror, as its text +function throwsAString() { + const worker = new Worker((self: WorkerScope) => { + self.onmessage = (e: MessageEvent) => { + self.close(); + throw "plain text"; + }; + }); + + worker.postMessage(0); + const log = new Shared(new Log()); + worker.onerror = (e: ErrorEvent) => { + log.value.add(e.message); + }; + worker.join(); + assert(log.value.lines.length == 1 && log.value.lines[0] == "plain text", "a thrown string"); +} + +function main() { + handlerThrows(); + bodyThrows(); + throwsAString(); + print("ALL DONE"); +}