Function pointer type for add-on provided functions that allow the user to be notified when externally-owned data is ready to be cleaned up because the object with which it was associated with, has been garbage-collected.
The user must provide a function satisfying the following signature which would get called upon the object's collection.
Currently, can be used for finding out when objects that have external data are collected.
In some cases it is useful to be able to get more detailed information, including a string representing the error as well as VM (engine)-specific information.
The native instance can be retrieved later using
(That object was created from the constructor function's, so it already has definitions of all the instance properties and methods.)
Typically when wrapping a class instance, a finalize callback should be provided that simply deletes the native instance that is received as the argument to the finalize callback.
The optional returned reference is initially a weak reference, meaning it has a reference count of 0.
Typically this reference count would be incremented temporarily during async operations that require the instance to remain valid.
CAUTION: The optional returned reference (if obtained) should be deleted via ONLY in response to the finalize callback invocation.
(If it is deleted before then, then the finalize callback may never be invoked.) Therefore, when obtaining a reference a finalize callback is also required in order to enable correct proper of the reference.
This API may modify the prototype chain of the wrapper object.
Afterward, additional manipulation of the wrapper's prototype chain may cause to fail.
Calling a second time on an object will return an error.
To associate another native instance with the object, use first.
The object associated with the native instance.
Pointer to the wrapped native instance.
If the callback is for an instance method or accessor, then the argument to the callback is the wrapper object; the wrapped C++ instance that is the target of the call can be obtained then by calling on the wrapper object.
Simple Asynchronous Operations
Addon modules often need to leverage async helpers from libuv as part of their implementation. This allows them to schedule work to be executed asynchronously so that their methods can return in advance of the work being completed. This is important in order to allow them to avoid blocking overall execution of the Node.js application.
N-API provides an ABI-stable interface for these supporting functions which covers the most common asynchronous use cases.
N-API defines the napi_work structure which is used to manage asynchronous workers. Instances are created/deleted with and
The and callbacks are functions that will be invoked when the executor is ready to execute and when it completes its task respectively. These functions implement the following interfaces:
When these methods are invoked, the parameter passed will be the addon-provided data that was passed into the call.
Once created the async worker can be queued for execution using the function:
can be used if the work needs to be cancelled before the work has started execution.
After calling, the callback will be invoked with a status value of
The work should not be deleted before the callback invocation, even when it was cancelled.
An optional object associated with the async work that will be passed to possible
Identifier for the kind of resource that is being provided for diagnostic information exposed by the API.
The native function which should be called to execute the logic asynchronously.
The given function is called from a worker pool thread and can execute in parallel with the main event loop thread.
The native function which will be called when the asynchronous logic is completed or is cancelled.
The given function is called from the main event loop thread.
User-provided data context.This will be passed back into the execute and complete functions.
which is the handle to the newly created async work.
This API allocates a work object that is used to execute logic asynchronously.
It should be freed using once the work is no longer required.
should be a null-terminated, UTF-8-encoded string
The identifier is provided by the user and should be representative of the type of async work being performed.
It is also recommended to apply namespacing to the identifier, e.g. by including the module name.
See the for more information.
The handle returned by the call to
This API frees a previously allocated work object.
This API requests that the previously allocated work be scheduled for execution.
This API cancels queued work if it has not yet been started.
If it has already started executing, it cannot be cancelled and will be returned.
Custom Asynchronous Operations
The simple asynchronous work APIs above may not be appropriate for every scenario.
When using any other asynchronous mechanism, the following APIs are necessary to ensure an asynchronous operation is properly tracked by the runtime.
The initialized async context.
The async context to be destroyed.
Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from
However is also allowed, which indicates the current async context (if any) is to be used for the callback.
The object passed to the called function.
The count of elements in the array.
This API is similar to
It is a fairly simple wrapper around
Note it is not necessary to use from within a; in that situation the callback's async context has already been set up, so a direct call to is sufficient and appropriate.
Use of the function may be required when implementing custom async behavior that does not use
The newly created scope.
There are cases (for example resolving promises) where it is necessary to have the equivalent of the scope associated with a callback in place when making certain N-API calls. If there is no other script on the stack the
functions can be used to open/close the required scope.
The scope to be closed.
A pointer to version information for Node.js itself.
This function fills the struct with the major, minor, and patch
version of Node.js that is currently running, and the field with the
The returned buffer is statically allocated and does not need to be freed.
The highest version of N-API supported.
This API returns the highest N-API version supported by the Node.js runtime. N-API is planned to be additive such that newer releases of Node.js may support additional API functions. In order to allow an addon to use a newer function when running with versions of Node.js that support it, while providing fallback behavior when running with Node.js versions that don't support it:
Call to determine if the API is available.
If available, dynamically load a pointer to the function using
Use the dynamically loaded pointer to invoke the function.
If the function is not available, provide an alternate implementation that does not use the function.
The adjusted value
N-API provides facilities for creating objects as described in
It implements promises as a pair of
When a promise is created by, a "deferred"
object is created and returned alongside the
The deferred object is
bound to the created and is the only means to resolve or reject the using or
deferred object that is created by is freed by or
For example, to create a promise and pass it to an asynchronous worker:
// Create the promise.
// Pass the deferred to a function that performs an asynchronous action.
// Return the promise to JS
The above function would perform its asynchronous action and then it would resolve or reject the deferred, thereby concluding the promise and freeing the deferred:
// Create a value with which to conclude the deferred.
// Resolve or reject the promise associated with the deferred depending on
// whether the asynchronous action succeeded.
// At this point the deferred has been freed, so we should assign NULL to it.
A newly created deferred object which can later be passed to or to resolve resp.
the associated promise.
The deferred object whose associated promise to resolve.
The value with which to resolve the promise.
The deferred object is freed upon successful completion.
The promise to examine
Flag indicating whether is a native promise
object - that is, a promise object created by the underlying engine.
The value resulting from having executed the script.
N-API provides a function for getting the current event loop associated with a specific
The current libuv loop instance.