Skip to content

Latest commit

 

History

History
80 lines (55 loc) · 2.53 KB

escapable_handle_scope.md

File metadata and controls

80 lines (55 loc) · 2.53 KB
Raw

EscapableHandleScope

The Napi::EscapableHandleScope class is used to manage the lifetime of object handles which are created through the use of node-addon-api. These handles keep an object alive in the heap in order to ensure that the objects are not collected by the garbage collector while native code is using them. A handle may be created when any new node-addon-api Value or one of its subclasses is created or returned.

The Napi::EscapableHandleScope is a special type of Napi::HandleScope which allows a single handle to be "promoted" to an outer scope.

For more details refer to the section titled Object lifetime management.

Methods

Constructor

Creates a new escapable handle scope.

Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi::Env env);
  • [in] Env: The environment in which to construct the Napi::EscapableHandleScope object.

Returns a new Napi::EscapableHandleScope

Constructor

Creates a new escapable handle scope.

Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope);
  • [in] env: napi_env in which the scope passed in was created.
  • [in] scope: pre-existing napi_handle_scope.

Returns a new Napi::EscapableHandleScope instance which wraps the napi_escapable_handle_scope handle passed in. This can be used to mix usage of the C Node-API and node-addon-api.

operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const

Returns the Node-API napi_escapable_handle_scope wrapped by the Napi::EscapableHandleScope object. This can be used to mix usage of the C Node-API and node-addon-api by allowing the class to be used be converted to a napi_escapable_handle_scope.

Destructor

Napi::EscapableHandleScope::~EscapableHandleScope();

Deletes the Napi::EscapableHandleScope instance and allows any objects/handles created in the scope to be collected by the garbage collector. There is no guarantee as to when the garbage collector will do this.

Escape

napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee);
  • [in] escapee: Napi::Value or napi_env to promote to the outer scope

Returns Napi::Value which can be used in the outer scope. This method can be called at most once on a given Napi::EscapableHandleScope. If it is called more than once an exception will be thrown.

Env

Napi::Env Napi::EscapableHandleScope::Env() const;

Returns the Napi::Env associated with the Napi::EscapableHandleScope.