From 72a1447707f2079387ff45a5ed222d423e132ef2 Mon Sep 17 00:00:00 2001 From: Tim Seckinger Date: Sun, 15 Dec 2019 21:36:50 +0000 Subject: [PATCH] docs: give recommendation on jest-worker end() Promises (#9310) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: give recommendation on jest-worker end() Promises * Update packages/jest-worker/README.md Co-Authored-By: Michał Pierzchała * Update packages/jest-worker/README.md Co-Authored-By: Michał Pierzchała * Update README.md --- packages/jest-worker/README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/packages/jest-worker/README.md b/packages/jest-worker/README.md index 247b68b748e9..6efbc0587387 100644 --- a/packages/jest-worker/README.md +++ b/packages/jest-worker/README.md @@ -95,23 +95,33 @@ The arguments that will be passed to the `setup` method during initialization. ## Worker +### Methods + The returned `Worker` instance has all the exposed methods, plus some additional ones to interact with the workers itself: -### `getStdout(): Readable` +#### `getStdout(): Readable` Returns a `ReadableStream` where the standard output of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`. -### `getStderr(): Readable` +#### `getStderr(): Readable` Returns a `ReadableStream` where the standard error of all workers is piped. Note that the `silent` option of the child workers must be set to `true` to make it work. This is the default set by `jest-worker`, but keep it in mind when overriding options through `forkOptions`. -### `end()` +#### `end()` Finishes the workers by killing all workers. No further calls can be done to the `Worker` instance. Returns a Promise that resolves with `{ forceExited: boolean }` once all workers are dead. If `forceExited` is `true`, at least one of the workers did not exit gracefully, which likely happened because it executed a leaky task that left handles open. This should be avoided, force exiting workers is a last resort to prevent creating lots of orphans. -**Note:** Each worker has a unique id (index that starts with `1`) which is available on `process.env.JEST_WORKER_ID` +**Note:** + +`await`ing the `end()` Promise immediately after the workers are no longer needed before proceeding to do other useful things in your program may not be a good idea. If workers have to be force exited, `jest-worker` may go through multiple stages of force exiting (e.g. SIGTERM, later SIGKILL) and give the worker overall around 1 second time to exit on its own. During this time, your program will wait, even though it may not be necessary that all workers are dead before continuing execution. + +Consider deliberately leaving this Promise floating (unhandled resolution). After your program has done the rest of its work and is about to exit, the Node process will wait for the Promise to resolve after all workers are dead as the last event loop task. That way you parallelized computation time of your program and waiting time and you didn't delay the outputs of your program unnecessarily. + +### Worker IDs + +Each worker has a unique id (index that starts with `1`), which is available inside the worker as `process.env.JEST_WORKER_ID`. ## Setting up and tearing down the child process