From 9ad901ef44d7ea83e230629a4b70e17b989ab20d Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 17 Feb 2016 11:10:46 -0800 Subject: [PATCH] doc: improve unhandledException doc copy Rework the doc a bit to tighten it up, including removing the use of `you` Fix some line wrapping issues. PR-URL: https://github.com/nodejs/node/pull/5287 Reviewed-By: Roman Klauke Reviewed-By: Sakthipriyan Vairamani ... --- doc/api/process.markdown | 68 +++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/doc/api/process.markdown b/doc/api/process.markdown index ca2971328025c5..0c046d66e2d851 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -7,12 +7,13 @@ It is an instance of [`EventEmitter`][]. ## Event: 'beforeExit' -This event is emitted when Node.js empties its event loop and has nothing else to -schedule. Normally, Node.js exits when there is no work scheduled, but a listener -for `'beforeExit'` can make asynchronous calls, and cause Node.js to continue. +This event is emitted when Node.js empties its event loop and has nothing else +to schedule. Normally, Node.js exits when there is no work scheduled, but a +listener for `'beforeExit'` can make asynchronous calls, and cause Node.js to +continue. -`'beforeExit'` is not emitted for conditions causing explicit termination, such as -[`process.exit()`][] or uncaught exceptions, and should not be used as an +`'beforeExit'` is not emitted for conditions causing explicit termination, such +as [`process.exit()`][] or uncaught exceptions, and should not be used as an alternative to the `'exit'` event unless the intention is to schedule more work. ## Event: 'exit' @@ -91,11 +92,12 @@ indefinitely) or upon process exit (more convenient for scripts). ## Event: 'uncaughtException' -Emitted when an exception bubbles all the way back to the event loop. If a -listener is added for this exception, the default action (which is to print -a stack trace and exit) will not occur. +The `'uncaughtException'` event is emitted when an exception bubbles all the +way back to the event loop. By default, Node.js handles such exceptions by +printing the stack trace to stderr and exiting. Adding a handler for the +`'uncaughtException'` event overrides this default behavior. -Example of listening for `'uncaughtException'`: +For example: ```js process.on('uncaughtException', (err) => { @@ -111,26 +113,27 @@ nonexistentFunc(); console.log('This will not run.'); ``` -Note that `'uncaughtException'` is a very crude mechanism for exception -handling. +### Warning: Using `'uncaughtException'` correctly -Do *not* use it as the Node.js equivalent of `On Error Resume Next`. An -unhandled exception means your application - and by extension Node.js itself - -is in an undefined state. Blindly resuming means *anything* could happen. +Note that `'uncaughtException'` is a crude mechanism for exception handling +intended to be used only as a last resort. The event *should not* be used as +an equivalent to `On Error Resume Next`. Unhandled exceptions inherently mean +that an application is in an undefined state. Attempting to resume application +code without properly recovering from the exception can cause additional +unforeseen and unpredictable issues. Exceptions thrown from within the event handler will not be caught. Instead the process will exit with a non zero exit code and the stack trace will be printed. This is to avoid infinite recursion. -Think of resuming as pulling the power cord when you are upgrading your system. -Nine out of ten times nothing happens - but the 10th time, your system is bust. +Attempting to resume normally after an uncaught exception can be similar to +pulling out of the power cord when upgrading a computer -- nine out of ten +times nothing happens - but the 10th time, the system becomes corrupted. -`'uncaughtException'` should be used to perform synchronous cleanup before -shutting down the process. It is not safe to resume normal operation after -`'uncaughtException'`. If you do use it, restart your application after every -unhandled exception! - -You have been warned. +The correct use of `'uncaughtException'` is to perform synchronous cleanup +of allocated resources (e.g. file descriptors, handles, etc) before shutting +down the process. It is not safe to resume normal operation after +`'uncaughtException'`. ## Event: 'unhandledRejection' @@ -142,8 +145,8 @@ a promise chain. This event is useful for detecting and keeping track of promises that were rejected whose rejections were not handled yet. This event is emitted with the following arguments: - - `reason` the object with which the promise was rejected (usually an [`Error`][] -instance). + - `reason` the object with which the promise was rejected (usually an + [`Error`][] instance). - `p` the promise that was rejected. Here is an example that logs every unhandled rejection to the console @@ -254,10 +257,10 @@ Note: - `SIGUSR1` is reserved by Node.js to start the debugger. It's possible to install a listener but that won't stop the debugger from starting. -- `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that resets - the terminal mode before exiting with code `128 + signal number`. If one of - these signals has a listener installed, its default behavior will be removed - (Node.js will no longer exit). +- `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that + resets the terminal mode before exiting with code `128 + signal number`. If + one of these signals has a listener installed, its default behavior will be + removed (Node.js will no longer exit). - `SIGPIPE` is ignored by default. It can have a listener installed. - `SIGHUP` is generated on Windows when the console window is closed, and on other platforms under various similar conditions, see signal(7). It can have a @@ -269,11 +272,12 @@ Note: - `SIGINT` from the terminal is supported on all platforms, and can usually be generated with `CTRL+C` (though this may be configurable). It is not generated when terminal raw mode is enabled. -- `SIGBREAK` is delivered on Windows when `CTRL+BREAK` is pressed, on non-Windows +- `SIGBREAK` is delivered on Windows when `CTRL+BREAK` is pressed, on + non-Windows platforms it can be listened on, but there is no way to send or generate it. -- `SIGWINCH` is delivered when the console has been resized. On Windows, this will - only happen on write to the console when the cursor is being moved, or when a - readable tty is used in raw mode. +- `SIGWINCH` is delivered when the console has been resized. On Windows, this + will only happen on write to the console when the cursor is being moved, or + when a readable tty is used in raw mode. - `SIGKILL` cannot have a listener installed, it will unconditionally terminate Node.js on all platforms. - `SIGSTOP` cannot have a listener installed.