async_hooks: multi-tenant promise hook api

doc/api/v8.md

@@ -564,8 +564,267 @@ added: v8.0.0
 A subclass of [`Deserializer`][] corresponding to the format written by
 [`DefaultSerializer`][].
 
+## Promise hooks
+
+The `promiseHooks` interface can be used to track promise lifecycle events.
+To track _all_ async activity, see [`async_hooks`][] which internally uses this
+module to produce promise lifecycle events in addition to events for other
+async resources. For request context management, see [`AsyncLocalStorage`][].
+
+```mjs
+import { promiseHooks } from 'v8';
+
+// There are four lifecycle events produced by promises:
+
+// The `init` event represents the creation of a promise. This could be a
+// direct creation such as with `new Promise(...)` or a continuation such
+// as `then()` or `catch()`. It also happens whenever an async function is
+// called or does an `await`. If a continuation promise is created, the
+// `parent` will be the promise it is a continuation from.
+function init(promise, parent) {
+  console.log('a promise was created', { promise, parent });
+}
+
+// The `settled` event happens when a promise receives a resolution or
+// rejection value. This may happen synchronously such as when using
+// `Promise.resolve()` on non-promise input.
+function settled(promise) {
+  console.log('a promise resolved or rejected', { promise });
+}
+
+// The `before` event runs immediately before a `then()` or `catch()` handler
+// runs or an `await` resumes execution.
+function before(promise) {
+  console.log('a promise is about to call a then handler', { promise });
+}
+
+// The `after` event runs immediately after a `then()` handler runs or when
+// an `await` begins after resuming from another.
+function after(promise) {
+  console.log('a promise is done calling a then handler', { promise });
+}
+
+// Lifecycle hooks may be started and stopped individually
+const stopWatchingInits = promiseHooks.onInit(init);
+const stopWatchingSettleds = promiseHooks.onSettled(settled);
+const stopWatchingBefores = promiseHooks.onBefore(before);
+const stopWatchingAfters = promiseHooks.onAfter(after);
+
+// Or they may be started and stopped in groups
+const stopHookSet = promiseHooks.createHook({
+  init,
+  settled,
+  before,
+  after
+});
+
+// To stop a hook, call the function returned at its creation.
+stopWatchingInits();
+stopWatchingSettleds();
+stopWatchingBefores();
+stopWatchingAfters();
+stopHookSet();
+```
+
+### `promiseHooks.onInit(init)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `init` {Function} The [`init` callback][] to call when a promise is created.
+* Returns: {Function} Call to stop the hook.
+
+**The `init` hook must be a plain function. Providing an async function will
+throw as it would produce an infinite microtask loop.**
+
+```mjs
+import { promiseHooks } from 'v8';
+
+const stop = promiseHooks.onInit((promise, parent) => {});
+```
+
+```cjs
+const { promiseHooks } = require('v8');
+
+const stop = promiseHooks.onInit((promise, parent) => {});
+```
+
+### `promiseHooks.onSettled(settled)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `settled` {Function} The [`settled` callback][] to call when a promise
+  is resolved or rejected.
+* Returns: {Function} Call to stop the hook.
+
+**The `settled` hook must be a plain function. Providing an async function will
+throw as it would produce an infinite microtask loop.**
+
+```mjs
+import { promiseHooks } from 'v8';
+
+const stop = promiseHooks.onSettled((promise) => {});
+```
+
+```cjs
+const { promiseHooks } = require('v8');
+
+const stop = promiseHooks.onSettled((promise) => {});
+```
+
+### `promiseHooks.onBefore(before)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `before` {Function} The [`before` callback][] to call before a promise
+  continuation executes.
+* Returns: {Function} Call to stop the hook.
+
+**The `before` hook must be a plain function. Providing an async function will
+throw as it would produce an infinite microtask loop.**
+
+```mjs
+import { promiseHooks } from 'v8';
+
+const stop = promiseHooks.onBefore((promise) => {});
+```
+
+```cjs
+const { promiseHooks } = require('v8');
+
+const stop = promiseHooks.onBefore((promise) => {});
+```
+
+### `promiseHooks.onAfter(after)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `after` {Function} The [`after` callback][] to call after a promise
+  continuation executes.
+* Returns: {Function} Call to stop the hook.
+
+**The `after` hook must be a plain function. Providing an async function will
+throw as it would produce an infinite microtask loop.**
+
+```mjs
+import { promiseHooks } from 'v8';
+
+const stop = promiseHooks.onAfter((promise) => {});
+```
+
+```cjs
+const { promiseHooks } = require('v8');
+
+const stop = promiseHooks.onAfter((promise) => {});
+```
+
+### `promiseHooks.createHook(callbacks)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `callbacks` {Object} The [Hook Callbacks][] to register
+  * `init` {Function} The [`init` callback][].
+  * `before` {Function} The [`before` callback][].
+  * `after` {Function} The [`after` callback][].
+  * `settled` {Function} The [`settled` callback][].
+* Returns: {Function} Used for disabling hooks
+
+**The hook callbacks must be plain functions. Providing async functions will
+throw as it would produce an infinite microtask loop.**
+
+Registers functions to be called for different lifetime events of each promise.
+
+The callbacks `init()`/`before()`/`after()`/`settled()` are called for the
+respective events during a promise's lifetime.
+
+All callbacks are optional. For example, if only promise creation needs to
+be tracked, then only the `init` callback needs to be passed. The
+specifics of all functions that can be passed to `callbacks` is in the
+[Hook Callbacks][] section.
+
+```mjs
+import { promiseHooks } from 'v8';
+
+const stopAll = promiseHooks.createHook({
+  init(promise, parent) {}
+});
+```
+
+```cjs
+const { promiseHooks } = require('v8');
+
+const stopAll = promiseHooks.createHook({
+  init(promise, parent) {}
+});
+```
+
+### Hook callbacks
+
+Key events in the lifetime of a promise have been categorized into four areas:
+creation of a promise, before/after a continuation handler is called or around
+an await, and when the promise resolves or rejects.
+
+While these hooks are similar to those of [`async_hooks`][] they lack a
+`destroy` hook. Other types of async resources typically represent sockets or
+file descriptors which have a distinct "closed" state to express the `destroy`
+lifecycle event while promises remain usable for as long as code can still
+reach them. Garbage collection tracking is used to make promises fit into the
+`async_hooks` event model, however this tracking is very expensive and they may
+not necessarily ever even be garbage collected.
+
+Because promises are asynchronous resources whose lifecycle is tracked
+via the promise hooks mechanism, the `init()`, `before()`, `after()`, and
+`settled()` callbacks *must not* be async functions as they create more
+promises which would produce an infinite loop.
+
+While this API is used to feed promise events into [`async_hooks`][], the
+ordering between the two is considered undefined. Both APIs are multi-tenant
+and therefore could produce events in any order relative to each other.
+
+#### `init(promise, parent)`
+
+* `promise` {Promise} The promise being created.
+* `parent` {Promise} The promise continued from, if applicable.
+
+Called when a promise is constructed. This _does not_ mean that corresponding
+`before`/`after` events will occur, only that the possibility exists. This will
+happen if a promise is created without ever getting a continuation.
+
+#### `before(promise)`
+
+* `promise` {Promise}
+
+Called before a promise continuation executes. This can be in the form of
+`then()`, `catch()`, or `finally()` handlers or an `await` resuming.
+
+The `before` callback will be called 0 to N times. The `before` callback
+will typically be called 0 times if no continuation was ever made for the
+promise. The `before` callback may be called many times in the case where
+many continuations have been made from the same promise.
+
+#### `after(promise)`
+
+* `promise` {Promise}
+
+Called immediately after a promise continuation executes. This may be after a
+`then()`, `catch()`, or `finally()` handler or before an `await` after another
+`await`.
+
+#### `settled(promise)`
+
+* `promise` {Promise}
+
+Called when the promise receives a resolution or rejection value. This may
+occur synchronously in the case of `Promise.resolve()` or `Promise.reject()`.
+
 [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
+[Hook Callbacks]: #hook_callbacks
 [V8]: https://developers.google.com/v8/
+[`AsyncLocalStorage`]: async_context.md#class_asynclocalstorage
 [`Buffer`]: buffer.md
 [`DefaultDeserializer`]: #class-v8defaultdeserializer
 [`DefaultSerializer`]: #class-v8defaultserializer
@@ -575,15 +834,20 @@ A subclass of [`Deserializer`][] corresponding to the format written by
 [`GetHeapSpaceStatistics`]: https://v8docs.nodesource.com/node-13.2/d5/dda/classv8_1_1_isolate.html#ac673576f24fdc7a33378f8f57e1d13a4
 [`NODE_V8_COVERAGE`]: cli.md#node_v8_coveragedir
 [`Serializer`]: #class-v8serializer
+[`after` callback]: #after_promise
+[`async_hooks`]: async_hooks.md
+[`before` callback]: #before_promise
 [`buffer.constants.MAX_LENGTH`]: buffer.md#bufferconstantsmax_length
 [`deserializer._readHostObject()`]: #deserializer_readhostobject
 [`deserializer.transferArrayBuffer()`]: #deserializertransferarraybufferid-arraybuffer
+[`init` callback]: #init_promise_parent
 [`serialize()`]: #v8serializevalue
 [`serializer._getSharedArrayBufferId()`]: #serializer_getsharedarraybufferidsharedarraybuffer
 [`serializer._writeHostObject()`]: #serializer_writehostobjectobject
 [`serializer.releaseBuffer()`]: #serializerreleasebuffer
 [`serializer.transferArrayBuffer()`]: #serializertransferarraybufferid-arraybuffer
 [`serializer.writeRawBytes()`]: #serializerwriterawbytesbuffer
+[`settled` callback]: #settled_promise
 [`v8.stopCoverage()`]: #v8stopcoverage
 [`v8.takeCoverage()`]: #v8takecoverage
 [`vm.Script`]: vm.md#new-vmscriptcode-options

lib/internal/async_hooks.js

@@ -8,6 +8,8 @@ const {
   Symbol,
 } = primordials;
 
+const promiseHooks = require('internal/promise_hooks');
+
 const async_wrap = internalBinding('async_wrap');
 const { setCallbackTrampoline } = async_wrap;
 /* async_hook_fields is a Uint32Array wrapping the uint32_t array of
@@ -51,8 +53,6 @@ const {
   executionAsyncResource: executionAsyncResource_,
   clearAsyncIdStack,
 } = async_wrap;
-// For performance reasons, only track Promises when a hook is enabled.
-const { setPromiseHooks } = async_wrap;
 // Properties in active_hooks are used to keep track of the set of hooks being
 // executed in case another hook is enabled/disabled. The new set of hooks is
 // then restored once the active set of hooks is finished executing.
@@ -374,6 +374,7 @@ function enableHooks() {
   async_hook_fields[kCheck] += 1;
 }
 
+let stopPromiseHook;
 function updatePromiseHookMode() {
   wantPromiseHook = true;
   let initHook;
@@ -383,12 +384,13 @@ function updatePromiseHookMode() {
   } else if (destroyHooksExist()) {
     initHook = destroyTracking;
   }
-  setPromiseHooks(
-    initHook,
-    promiseBeforeHook,
-    promiseAfterHook,
-    promiseResolveHooksExist() ? promiseResolveHook : undefined,
-  );
+  if (stopPromiseHook) stopPromiseHook();
+  stopPromiseHook = promiseHooks.createHook({
+    init: initHook,
+    before: promiseBeforeHook,
+    after: promiseAfterHook,
+    settled: promiseResolveHooksExist() ? promiseResolveHook : undefined
+  });
 }
 
 function disableHooks() {
@@ -402,8 +404,8 @@ function disableHooks() {
 }
 
 function disablePromiseHookIfNecessary() {
-  if (!wantPromiseHook) {
-    setPromiseHooks(undefined, undefined, undefined, undefined);
+  if (!wantPromiseHook && stopPromiseHook) {
+    stopPromiseHook();
   }
 }