finalization.md

Finalization

Various node-addon-api methods accept a templated Finalizer finalizeCallback parameter. This parameter represents a native callback function that runs in response to a garbage collection event. A finalizer is considered a basic finalizer if the callback only utilizes a certain subset of APIs, which may provide more efficient memory management, optimizations, improved execution, or other benefits.

In general, it is best to use basic finalizers whenever possible (eg. when access to JavaScript is not needed). The NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS preprocessor directive can be defined to ensure that all finalizers are basic.

Finalizers

The callback takes Napi::Env as its first argument:

Example

Napi::External<int>::New(Env(), new int(1), [](Napi::Env env, int* data) {
  env.RunScript("console.log('Finalizer called')");
  delete data;
});

Basic Finalizers

Use of basic finalizers may allow the engine to perform optimizations when scheduling or executing the callback. For example, V8 does not allow access to the engine heap during garbage collection. Restricting finalizers from accessing the engine heap allows the callback to execute during garbage collection, providing a chance to free native memory eagerly.

In general, APIs that access engine heap are not allowed in basic finalizers.

The callback takes Napi::BasicEnv as its first argument:

Example

Napi::ArrayBuffer::New(
    Env(), data, length, [](Napi::BasicEnv /*env*/, void* finalizeData) {
      delete[] static_cast<uint8_t*>(finalizeData);
    });

Scheduling Finalizers

In addition to passing finalizers to Napi::Externals and other Node-API constructs, Napi::BasicEnv::PostFinalize(Napi::BasicEnv, Finalizer) can be used to schedule a callback to run outside of the garbage collector finalization. Since the associated native memory may already be freed by the basic finalizer, any additional data may be passed eg. via the finalizer's parameters (T data*, Hint hint*) or via lambda capture. This allows for freeing native data in a basic finalizer, while executing any JavaScript code in an additional finalizer.

Example

// Native Add-on

#include <iostream>
#include <memory>
#include "napi.h"

using namespace Napi;

// A structure representing some data that uses a "large" amount of memory.
class LargeData {
 public:
  LargeData() : id(instances++) {}
  size_t id;

  static size_t instances;
};

size_t LargeData::instances = 0;

// Basic finalizer to free `LargeData`. Takes ownership of the pointer and
// frees its memory after use.
void MyBasicFinalizer(Napi::BasicEnv env, LargeData* data) {
  std::unique_ptr<LargeData> instance(data);
  std::cout << "Basic finalizer for instance " << instance->id
            << " called\n";

  // Register a finalizer. Since the instance will be deleted by
  // the time this callback executes, pass the instance's `id` via lambda copy
  // capture and _not_ a reference capture that accesses `this`.
  env.PostFinalizer([instanceId = instance->id](Napi::Env env) {
    env.RunScript("console.log('Finalizer for instance " +
                  std::to_string(instanceId) + " called');");
  });

  // Free the `LargeData` held in `data` once `instance` goes out of scope.
}

Value CreateExternal(const CallbackInfo& info) {
  // Create a new instance of LargeData.
  auto instance = std::make_unique<LargeData>();

  // Wrap the instance in an External object, registering a basic
  // finalizer that will delete the instance to free the "large" amount of
  // memory.
  return External<LargeData>::New(info.Env(), instance.release(), MyBasicFinalizer);
}

Object Init(Napi::Env env, Object exports) {
  exports["createExternal"] = Function::New(env, CreateExternal);
  return exports;
}

NODE_API_MODULE(addon, Init)

// JavaScript

const { createExternal } = require('./addon.node');

for (let i = 0; i < 5; i++) {
  const ext = createExternal();
  // ... do something with `ext` ..
}

console.log('Loop complete');
await new Promise(resolve => setImmediate(resolve));
console.log('Next event loop cycle');

Possible output:

Basic finalizer for instance 0 called
Basic finalizer for instance 1 called
Basic finalizer for instance 2 called
Basic finalizer for instance 3 called
Basic finalizer for instance 4 called
Loop complete
Finalizer for instance 3 called
Finalizer for instance 4 called
Finalizer for instance 1 called
Finalizer for instance 2 called
Finalizer for instance 0 called
Next event loop cycle

If the garbage collector runs during the loop, the basic finalizers execute and display their logging message synchronously during the loop execution. The additional finalizers execute at some later point after the garbage collection cycle.