The module provides an API to register callbacks tracking the lifetime of asynchronous resources created inside a Node.js application.
It can be accessed using:
An asynchronous resource represents an object with an associated callback.
This callback may be called multiple times, for example, the event in, or just a single time like in
A resource can also be closed before the callback is called.
does not explicitly distinguish between these different cases but will represent them as the abstract concept that is a resource.
Following is a simple overview of the public API.
Return the ID of the current execution context.
Return the ID of the handle responsible for triggering the callback of the current execution scope to call.
Create a new instance.
All of these callbacks are optional.
Allow callbacks of this instance to call.
This is not an implicit action after running the constructor, and must be explicitly run to begin executing callbacks.
Disable listening for new asynchronous events.
The following are the callbacks that can be passed to
init is called during object construction.
The resource may not have completed construction when this callback runs, therefore all fields of the resource referenced by may not have been populated.
before is called just before the resource's callback is called.
It can be called 0-N times for handles (e.g. TCPWrap), and will be called exactly 1 time for requests (e.g. FSReqWrap).
after is called just after the resource's callback has finished.
destroy is called when an instance is destroyed.
promiseResolve is called only for promise resources, when the function passed to the constructor is invoked (either directly or through other means of resolving a promise).
The to register
Returns: Instance used for disabling and enabling hooks
Registers functions to be called for different lifetime events of each async operation.
The callbacks are called for the respective asynchronous event during a resource's lifetime.
For example, if only resource cleanup needs to be tracked, then only the callback needs to be passed.
The specifics of all functions that can be passed to is in the section.
Note that the callbacks will be inherited via the prototype chain:
If any callbacks throw, the application will print the stack trace and exit.
The exit path does follow that of an uncaught exception, but all listeners are removed, thus forcing the process to exit.
The callbacks will still be called unless the application is run with, in which case a stack trace will be printed and the application exits, leaving a core file.
The reason for this error handling behavior is that these callbacks are running at potentially volatile points in an object's lifetime, for example during class construction and destruction. Because of this, it is deemed necessary to bring down the process quickly in order to prevent an unintentional abort in the future. This is subject to change in the future if a comprehensive analysis is performed to ensure an exception can follow the normal control flow without unintentional side effects.
Printing in callbacks
Because printing to the console is an asynchronous operation, will cause the callbacks to be called.
Using or similar asynchronous operations inside an callback function will thus cause an infinite recursion.
An easy solution to this when debugging is to use a synchronous logging operation such as
This will print to because is the file descriptor for stdout and will not invoke recursively because it is synchronous.
use a function like this one when debugging inside an AsyncHooks callback
If an asynchronous operation is needed for logging, it is possible to keep track of what caused the asynchronous operation using the information provided by itself. The logging should then be skipped when it was the logging itself that caused callback to call. By doing this the otherwise infinite recursion is broken.
Returns: A reference to
Enable the callbacks for a given instance. If no callbacks are provided enabling is a noop.
The instance is disabled by default. If the instance should be enabled immediately after creation, the following pattern can be used.
Disable the callbacks for a given instance from the global pool of callbacks to be executed. Once a hook has been disabled it will not be called again until enabled.
For API consistency also returns the instance.
Key events in the lifetime of asynchronous events have been categorized into
four areas: instantiation, before/after the callback is called, and when the
instance is destroyed.
A unique ID for the async resource.
The type of the async resource.
The unique ID of the async resource in whose
execution context this async resource was created.
Reference to the resource representing the async operation, needs to be released during
Called when a class is constructed that has the possibility to emit an asynchronous event. This does not mean the instance must call before is called, only that the possibility exists.
This behavior can be observed by doing something like opening a resource then closing it before the resource can be used. The following snippet demonstrates this.
Every new resource is assigned an ID that is unique within the scope of the current process.
The is a string identifying the type of resource that caused to be called. Generally, it will correspond to the name of the resource's constructor.
There is also the resource type, which is used to track instances and asynchronous work scheduled by them.
Users are able to define their own when using the public embedder API.
It is possible to have type name collisions. Embedders are encouraged to use unique prefixes, such as the npm package name, to prevent collisions when listening to the hooks.
is the of the resource that caused (or "triggered") the new resource to initialize and that caused to call.
This is different from that only shows when a resource was created, while shows why a resource was created.
The following is a simple demonstration of
Output when hitting the server with
The is the new connection from the client.
When a new connection is made, the instance is immediately constructed.