Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Warn against uncaughtException dependency. #6378

Closed
wants to merge 1 commit into from
Closed

doc: Warn against uncaughtException dependency. #6378

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
29 changes: 17 additions & 12 deletions doc/api/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,10 +149,11 @@ most convenient for scripts).
added: v0.1.18
-->

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.
The `'uncaughtException'` event is emitted when an uncaught JavaScript
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.

The listener function is called with the `Error` object passed as the only
argument.
Expand All @@ -161,7 +162,7 @@ For example:

```js
process.on('uncaughtException', (err) => {
console.log(`Caught exception: ${err}`);
fs.writeSync(1, `Caught exception: ${err}`);
});

setTimeout(() => {
Expand Down Expand Up @@ -192,20 +193,24 @@ times nothing happens - but the 10th time, the system becomes corrupted.

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'`.
down the process. **It is not safe to resume normal operation after
`'uncaughtException'`.**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "normal" needs to be defined, otherwise people are likely to interpret as "write the error into a remote mongodb and exit", or something of the like (see #6561). Its not safe to do anything async in the uncaughtException handler ... you can make some sync calls, and then throw the exception or exit.

With console.log being async... I'm not even sure how reasonable calling it is.

/cc @bnoordhuis

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, "normal" is pretty poorly defined here. But I think that's because "normal" can mean different things in different situations for different applications. I agree, however, that being explicit about async operations is probably good. This, and any other "you must not do X" rules would be great. This would allow developers to make their own decisions about fail-fast behavior or not - knowing the tradeoffs.


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'
<!-- YAML
added: v1.4.1
-->

The `'unhandledRejection`' event is emitted whenever a `Promise` is rejected and
no error handler is attached to the promise within a turn of the event loop.
no error handler is attached to the promise within a turn of the event loop.
When programming with Promises, exceptions are encapsulated as "rejected
promises". Rejections can be caught and handled using [`promise.catch()`][] and
are propagated through a `Promise` chain. The `'unhandledRejection'` event is
useful for detecting and keeping track of promises that were rejected whose
useful for detecting and keeping track of promises that were rejected whose
rejections have not yet been handled.

The listener function is called with the following arguments:
Expand Down Expand Up @@ -636,7 +641,7 @@ An example of this object looks like:
SHLVL: '1',
HOME: '/Users/maciej',
LOGNAME: 'maciej',
_: '/usr/local/bin/node'
_: '/usr/local/bin/node'
}
```

Expand Down Expand Up @@ -1107,10 +1112,10 @@ console.log(util.inspect(process.memoryUsage()));
Will generate:

```js
{
{
rss: 4935680,
heapTotal: 1826816,
heapUsed: 650472
heapUsed: 650472
}
```

Expand Down