Browse Source

doc: Warn against `uncaughtException` dependency.

State in the documentation that `uncaughtException` is not a reliable
way to restart a crashed application, and clarify that an application
may crash in ways that do not trigger this event.

Use a documented synchronous function in example code.

Fixes: https://github.com/nodejs/node/issues/6223

Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/6378
v6.x
Lance Ball 9 years ago
committed by Evan Lucas
parent
commit
9c274e32fd
  1. 19
      doc/api/process.md

19
doc/api/process.md

@ -149,10 +149,11 @@ most convenient for scripts).
added: v0.1.18 added: v0.1.18
--> -->
The `'uncaughtException'` event is emitted when an exception bubbles all the The `'uncaughtException'` event is emitted when an uncaught JavaScript
way back to the event loop. By default, Node.js handles such exceptions by exception bubbles all the way back to the event loop. By default, Node.js
printing the stack trace to `stderr` and exiting. Adding a handler for the handles such exceptions by printing the stack trace to `stderr` and exiting.
`'uncaughtException'` event overrides this default behavior. Adding a handler for the `'uncaughtException'` event overrides this default
behavior.
The listener function is called with the `Error` object passed as the only The listener function is called with the `Error` object passed as the only
argument. argument.
@ -161,7 +162,7 @@ For example:
```js ```js
process.on('uncaughtException', (err) => { process.on('uncaughtException', (err) => {
console.log(`Caught exception: ${err}`); fs.writeSync(1, `Caught exception: ${err}`);
}); });
setTimeout(() => { setTimeout(() => {
@ -192,8 +193,12 @@ times nothing happens - but the 10th time, the system becomes corrupted.
The correct use of `'uncaughtException'` is to perform synchronous cleanup The correct use of `'uncaughtException'` is to perform synchronous cleanup
of allocated resources (e.g. file descriptors, handles, etc) before shutting of allocated resources (e.g. file descriptors, handles, etc) before shutting
down the process. It is not safe to resume normal operation after down the process. **It is not safe to resume normal operation after
`'uncaughtException'`. `'uncaughtException'`.**
To restart a crashed application in a more reliable way, whether `uncaughtException`
is emitted or not, an external monitor should be employed in a separate process
to detect application failures and recover or restart as needed.
### Event: 'unhandledRejection' ### Event: 'unhandledRejection'
<!-- YAML <!-- YAML

Loading…
Cancel
Save