process: add flag for uncaught exception abort

Introduce `process.shouldAbortOnUncaughtException` to control
`--abort-on-uncaught-exception` behaviour, and implement
some of the domains functionality on top of it.

PR-URL: https://github.com/nodejs/node/pull/17159
Refs: https://github.com/nodejs/node/issues/17143
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Andreas Madsen <amwebdk@gmail.com>

3 files changed, 69 insertions, 0 deletions

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 2d8cccb8a4..b8ea4826de 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -183,6 +183,10 @@ added: v0.10
 Aborting instead of exiting causes a core file to be generated for post-mortem
 analysis using a debugger (such as `lldb`, `gdb`, and `mdb`).
 
+*Note*: If this flag is passed, the behavior can still be set to not abort
+through [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage
+of the `domain` module that uses it).
+
 ### `--trace-warnings`
 <!-- YAML
 added: v6.0.0
@@ -598,3 +602,4 @@ greater than `4` (its current default value).  For more information, see the
 [debugger]: debugger.html
 [emit_warning]: process.html#process_process_emitwarning_warning_type_code_ctor
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
+[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
diff --git a/doc/api/errors.md b/doc/api/errors.md
index d7b5de448f..5856c12091 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -729,6 +729,23 @@ A signing `key` was not provided to the [`sign.sign()`][] method.
 
 `c-ares` failed to set the DNS server.
 
+<a id="ERR_DOMAIN_CALLBACK_NOT_AVAILABLE"></a>
+### ERR_DOMAIN_CALLBACK_NOT_AVAILABLE
+
+The `domain` module was not usable since it could not establish the required
+error handling hooks, because
+[`process.setUncaughtExceptionCaptureCallback()`][] had been called at an
+earlier point in time.
+
+<a id="ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE"></a>
+### ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE
+
+[`process.setUncaughtExceptionCaptureCallback()`][] could not be called
+because the `domain` module has been loaded at an earlier point in time.
+
+The stack trace is extended to include the point in time at which the
+`domain` module had been loaded.
+
 <a id="ERR_ENCODING_INVALID_ENCODED_DATA"></a>
 ### ERR_ENCODING_INVALID_ENCODED_DATA
 
@@ -1459,6 +1476,15 @@ A Transform stream finished while it was still transforming.
 
 A Transform stream finished with data still in the write buffer.
 
+<a id="ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET"></a>
+### ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET
+
+[`process.setUncaughtExceptionCaptureCallback()`][] was called twice,
+without first resetting the callback to `null`.
+
+This error is designed to prevent accidentally overwriting a callback registered
+from another module.
+
 <a id="ERR_UNESCAPED_CHARACTERS"></a>
 ### ERR_UNESCAPED_CHARACTERS
 
@@ -1565,6 +1591,7 @@ Creation of a [`zlib`][] object failed due to incorrect configuration.
 [`new URLSearchParams(iterable)`]: url.html#url_constructor_new_urlsearchparams_iterable
 [`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
 [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback
+[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags
 [`server.listen()`]: net.html#net_server_listen
 [ES6 module]: esm.html
diff --git a/doc/api/process.md b/doc/api/process.md
index 755dfb537c..733abe4c65 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -1136,6 +1136,16 @@ if (process.getuid) {
 *Note*: This function is only available on POSIX platforms (i.e. not Windows
 or Android).
 
+## process.hasUncaughtExceptionCaptureCallback()
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {boolean}
+
+Indicates whether a callback has been set using
+[`process.setUncaughtExceptionCaptureCallback()`][].
+
 ## process.hrtime([time])
 <!-- YAML
 added: v0.7.6
@@ -1637,6 +1647,29 @@ if (process.getuid && process.setuid) {
 or Android).
 
 
+## process.setUncaughtExceptionCaptureCallback(fn)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `fn` {Function|null}
+
+The `process.setUncaughtExceptionCapture` function sets a function that will
+be invoked when an uncaught exception occurs, which will receive the exception
+value itself as its first argument.
+
+If such a function is set, the [`process.on('uncaughtException')`][] event will
+not be emitted. If `--abort-on-uncaught-exception` was passed from the
+command line or set through [`v8.setFlagsFromString()`][], the process will
+not abort.
+
+To unset the capture function, `process.setUncaughtExceptionCapture(null)`
+may be used. Calling this method with a non-`null` argument while another
+capture function is set will throw an error.
+
+*Note*: Using this function is mutually exclusive with using the
+deprecated [`domain`][] built-in module.
+
 ## process.stderr
 
 * {Stream}
@@ -1921,6 +1954,7 @@ cases:
 [`JSON.stringify` spec]: https://tc39.github.io/ecma262/#sec-json.stringify
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
+[`domain`]: domain.html
 [`end()`]: stream.html#stream_writable_end_chunk_encoding_callback
 [`net.Server`]: net.html#net_class_net_server
 [`net.Socket`]: net.html#net_class_net_socket
@@ -1930,11 +1964,14 @@ cases:
 [`process.exit()`]: #process_process_exit_code
 [`process.exitCode`]: #process_process_exitcode
 [`process.kill()`]: #process_process_kill_pid_signal
+[`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
+[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`promise.catch()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
 [`require()`]: globals.html#globals_require
 [`require.main`]: modules.html#modules_accessing_the_main_module
 [`require.resolve()`]: modules.html#modules_require_resolve_request_options
 [`setTimeout(fn, 0)`]: timers.html#timers_settimeout_callback_delay_args
+[`v8.setFlagsFromString()`]: v8.html#v8_v8_setflagsfromstring_flags
 [Child Process]: child_process.html
 [Cluster]: cluster.html
 [Duplex]: stream.html#stream_duplex_and_transform_streams