XeNote/.yarn/unplugged/node-addon-api-npm-3.0.2-4c22ea0673/node_modules/node-addon-api/doc/async_context.md

AsyncContext

The Napi::AsyncWorker class may not be appropriate for every scenario. When using any other async mechanism, introducing a new class Napi::AsyncContext is necessary to ensure an async operation is properly tracked by the runtime. The Napi::AsyncContext class can be passed to Napi::Function::MakeCallback() method to properly restore the correct async execution context.

Methods

Constructor

Creates a new Napi::AsyncContext.

explicit Napi::AsyncContext::AsyncContext(napi_env env, const char* resource_name);

• [in] env: The environment in which to create the Napi::AsyncContext.
• [in] resource_name: Null-terminated strings that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API.

Constructor

Creates a new Napi::AsyncContext.

explicit Napi::AsyncContext::AsyncContext(napi_env env, const char* resource_name, const Napi::Object& resource);

• [in] env: The environment in which to create the Napi::AsyncContext.
• [in] resource_name: Null-terminated strings that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API.
• [in] resource: Object associated with the asynchronous operation that will be passed to possible async_hooks.

Destructor

The Napi::AsyncContext to be destroyed.

virtual Napi::AsyncContext::~AsyncContext();

Env

Requests the environment in which the async context has been initially created.

Napi::Env Env() const;

Returns the Napi::Env environment in which the async context has been created.

Operator

Napi::AsyncContext::operator napi_async_context() const;

Returns the N-API napi_async_context wrapped by the Napi::AsyncContext object. This can be used to mix usage of the C N-API and node-addon-api.

Example

#include "napi.h"

void MakeCallbackWithAsyncContext(const Napi::CallbackInfo& info) {
  Napi::Function callback = info[0].As<Napi::Function>();
  Napi::Object resource = info[1].As<Napi::Object>();

  // Creat a new async context instance.
  Napi::AsyncContext context(info.Env(), "async_context_test", resource);

  // Invoke the callback with the async context instance.
  callback.MakeCallback(Napi::Object::New(info.Env()),
      std::initializer_list<napi_value>{}, context);

  // The async context instance is automatically destroyed here because it's
  // block-scope like `Napi::HandleScope`.
}