node-napi-threadsafe-deferred

A thread-safe variant of a Napi-Promise which can be resolved from any thread.

In case you stumble across the issue, that you tried to resolve or reject a promise from a thread different from the main javascript thread, this module is for you. It provides you the class ThreadSafeDeferred which is a replacement class for Napi::Promise::Deferred. It uses Napi::ThreadSafeFunction's release callback (which is called from the main thread) to resolve or reject the promise from there.

Installation

1. Install

npm i napi-threadsafe-deferred

2. Then add it to your binding.gyp

    ...
    "include_dirs": [
        ...
        "<!@(node -p \"require('napi-threadsafe-deferred').include\")"
        ...
    ],
    "dependencies": [
        ...
        "<!(node -p \"require('napi-threadsafe-deferred').gyp\")"
        ...
    ]
    ...

Usage

1. Include ThreadSafeDeferred.hpp.
2. In a function called from JavaScript create an instance by calling the constructor and save a reference or pointer to it, e.g.:

Napi::Value myFunctionBoundToJS(const Napi::CallbackInfo & info) {
    auto myDeferred = new ThreadSafeDeferred(Env());
    // -> store a pointer or reference to the deferred somewhere
    return myDeferred->Promise();
}

3. Call Resolve or Reject from any thread you like.

Promise resolution

You can resolve a promise without a value:

void functionCalledFromAnotherThread() {
    ...
    myDeferred.Reslove();
}

...with a value:

void functionCalledFromAnotherThread() {
    ...
    myDeferred.Reslove(THREADSAFE_DEFERRED_RESOLVER(Napi::Number::New(env, 42)));
}

Resolving with a value is done by passing a lambda call back which will be called from the main thread during promise resolution. THREADSAFE_DEFERRED_RESOLVER makes the symbols available as copy ([=])

You can manually pass a lambda, if you need more control over the symbols or if you want to use the callback to release memory:

void functionCalledFromAnotherThread() {
    ...
    myDeferred.Reslove([&something]{
        delete something;
        return Napi::Number::New(env, 42);
    });
}

Promise rejection

You can reject a promise using the Reject function without parameter or with a string, which is used as reason for the exception on which the rejection is based:

void functionCalledFromAnotherThread() {
    ...
    myDeferred.Reject("Gime gime gime - you tried to invoke man after midnight.");
    ...
}

Features and Caveats

As the resolution of the ThreadSafeDeferred is handled asynchronously - the object will - in case it resides on heap - delete itself after the underlying Napi::Promise::Deferred has been resolved. As the object is still needed after your call to Resolve or Reject you must not delete it yourself.