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
39 changes: 25 additions & 14 deletions docs/worker-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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".)
Expand Down Expand Up @@ -219,16 +217,31 @@ 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
instead made it run. A cut-down class does not show it, so the repro is the full one:
[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<MessageEvent<Out> | ErrorEvent>` (`type WorkerPost<Out>`). 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: <message>` 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:

Expand All @@ -252,16 +265,17 @@ 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.

## Tests (each runs under gc, rc, none and own unless it says otherwise)

- `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
Expand All @@ -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 ? <T>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<Out> | undefined` as written; `MessageQueue.take`
Expand Down
5 changes: 5 additions & 0 deletions src/core/core.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
7 changes: 7 additions & 0 deletions src/core/core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
106 changes: 67 additions & 39 deletions src/generics/lib.generics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1021,6 +1021,11 @@ class MessageEvent<T> {
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<Out> = MessageEvent<Out> | 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.
Expand All @@ -1030,14 +1035,14 @@ class WorkerScope<In, Out> {
onmessage: (e: MessageEvent<In>) => void;
private closing: boolean;

constructor(private toCreator: Shared<MessageQueue<Out>>, public name: string) {
constructor(private toCreator: Shared<MessageQueue<WorkerPost<Out>>>, public name: string) {
this.onmessage = (e: MessageEvent<In>) => {};
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<Out>(message));
}

// ends the worker once the handler running now returns; messages still queued for it are dropped
Expand All @@ -1048,40 +1053,51 @@ class WorkerScope<In, Out> {
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<In, Out> {
failed: boolean;
message: string;

constructor(public body: (self: WorkerScope<In, Out>) => void, public toWorker: Shared<MessageQueue<In>>,
public toCreator: Shared<MessageQueue<Out>>, public name: string) {
this.failed = false;
this.message = "";
}
public toCreator: Shared<MessageQueue<WorkerPost<Out>>>, 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<In, Out>(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 ? `${(<Error>e).message}` : `${e}`);
started = false;
}

while (started && !scope.closed) {
const message = this.toWorker.value.take();
if (message == undefined) {
break;
}

scope.onmessage(new MessageEvent<In>(message));
try {
scope.onmessage(new MessageEvent<In>(message));
} catch (e) {
scope.postError(e instanceof Error ? `${(<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 ? (<Error>e).message : `${e}`;
} finally {
// nothing more reaches the worker, and the creator sees it end
this.toWorker.value.close();
Expand All @@ -1102,13 +1118,16 @@ function __worker_entry<In, Out>(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<In, Out> {
// none set: join() drops what the worker posts. Always a function: see WorkerScope.onmessage.
onmessage: (e: MessageEvent<Out>) => void;
// none set: the error is printed to stderr, as a browser logs it to the console
onerror: (e: ErrorEvent) => void;
private toWorker: Shared<MessageQueue<In>>;
private toCreator: Shared<MessageQueue<Out>>;
private toCreator: Shared<MessageQueue<WorkerPost<Out>>>;
private start: WorkerStart<In, Out>;
private handle: Opaque;
private joined: boolean;
Expand All @@ -1119,11 +1138,14 @@ class Worker<In, Out> {
// each side holds its own handle to both queues: the fields keep one pair, the WorkerStart
// the other
const toWorker = new Shared(new MessageQueue<In>());
const toCreator = new Shared(new MessageQueue<Out>());
const toCreator = new Shared(new MessageQueue<WorkerPost<Out>>());
this.toWorker = toWorker;
this.toCreator = toCreator;
this.start = new WorkerStart<In, Out>(body, toWorker, toCreator, name);
this.onmessage = (e: MessageEvent<Out>) => {};
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)
Expand All @@ -1136,40 +1158,46 @@ class Worker<In, Out> {
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<Out> | 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<Out>(message);
if (post instanceof ErrorEvent) {
this.onerror(<ErrorEvent>post);
continue;
}

return <MessageEvent<Out>>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<Out>(message));
if (post instanceof ErrorEvent) {
this.onerror(<ErrorEvent>post);
} else {
this.onmessage(<MessageEvent<Out>>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
Expand Down
21 changes: 0 additions & 21 deletions tests/worker_echo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<int, int>((self: WorkerScope<int, int>) => {
self.onmessage = (e: MessageEvent<int>) => {
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");
}
Loading
Loading