From 1af3825563eec61c401cf521491d064b7325b860 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 26 Apr 2016 21:46:23 -0700 Subject: [PATCH 1/2] doc: expand documentation for process.exit() The fact that process.exit() interrupts pending async operations such as non-blocking i/o is becoming a bit more pronounced with the recent libuv update. This commit expands the documentation for `process.exit()` to explain clearly how it affects async operations. --- doc/api/process.md | 53 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/doc/api/process.md b/doc/api/process.md index bdadaaea88c164..7ea30989186965 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -706,8 +706,12 @@ Example: ## process.exit([code]) -Ends the process with the specified `code`. If omitted, exit uses the -'success' code `0`. +* `code` {Integer} The exit code. Defaults to `0`. + +The `process.exit()` methods instructs Node.js to terminate the process as +quickly as possible with the specified exit `code`. If the `code` is omitted, +exit uses either the 'success' code `0` or the value of `process.exitCode` if +specified. To exit with a 'failure' code: @@ -715,8 +719,47 @@ To exit with a 'failure' code: process.exit(1); ``` -The shell that executed Node.js should see the exit code as 1. +The shell that executed Node.js should see the exit code as `1`. + +It is important to note that calling `process.exit()` will force the process to +exit as quickly as possible *even if there are still asynchronous operations +pending* in the event loop, *including* i/o operations to `process.stdout` and +`process.stderr`. + +In most situations, it is not actually necessary to call `process.exit()` +explicitly. The Node.js process will exit on it's own *if there is no additional +work pending* in the event loop. The `process.exitCode` property can be set to +tell the process which exit code to use when the process exits gracefully. + +For instance, the following example illustrates a *misuse* of the +`process.exit()` method that could lead to data printed to stdout being +truncated and lost: +```js +// This is an example of what *not* to do: +if (someConditionNotMet()) { + printUsageToStdout(); + process.exit(1); +} +``` + +The reason this is problematic is because writes to `process.stdout` in Node.js +are *non-blocking* and may occur over multiple ticks of the Node.js event loop. +Calling `process.exit()`, however, forces the process to exit *before* those +additional writes to `stdout` can be performed. + +Rather than calling `process.exit()` directly, the code *should* set the +`process.exitCode` and allow the process to exit naturally by avoiding +scheduling any additional work for the event loop: + +```js +// How to properly set the exit code while letting +// the process exit gracefully. +if (someConditionNotMet()) { + printUsageToStdout(); + process.exitCode = 1; +} +``` ## process.exitCode @@ -724,8 +767,8 @@ A number which will be the process exit code, when the process either exits gracefully, or is exited via [`process.exit()`][] without specifying a code. -Specifying a code to [`process.exit(code)`][`process.exit()`] will override any previous -setting of `process.exitCode`. +Specifying a code to [`process.exit(code)`][`process.exit()`] will override any +previous setting of `process.exitCode`. ## process.getegid() From 948a79a6b5d5ceb003c8ca9a29462632cc2b67c4 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 28 Apr 2016 14:33:33 -0700 Subject: [PATCH 2/2] Address nits --- doc/api/process.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/api/process.md b/doc/api/process.md index 7ea30989186965..3a2cc1f780dee0 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -708,7 +708,7 @@ Example: * `code` {Integer} The exit code. Defaults to `0`. -The `process.exit()` methods instructs Node.js to terminate the process as +The `process.exit()` method instructs Node.js to terminate the process as quickly as possible with the specified exit `code`. If the `code` is omitted, exit uses either the 'success' code `0` or the value of `process.exitCode` if specified. @@ -723,8 +723,8 @@ The shell that executed Node.js should see the exit code as `1`. It is important to note that calling `process.exit()` will force the process to exit as quickly as possible *even if there are still asynchronous operations -pending* in the event loop, *including* i/o operations to `process.stdout` and -`process.stderr`. +pending* that have not yet completed fully, *including* I/O operations to +`process.stdout` and `process.stderr`. In most situations, it is not actually necessary to call `process.exit()` explicitly. The Node.js process will exit on it's own *if there is no additional @@ -761,6 +761,10 @@ if (someConditionNotMet()) { } ``` +If it is necessary to terminate the Node.js process due to an error condition, +throwing an *uncaught* error and allowing the process to terminate accordingly +is safer than calling `process.exit()`. + ## process.exitCode A number which will be the process exit code, when the process either