napi_thread_safe_promise
Version:
C++ napi threadd safe promises
132 lines (98 loc) • 4.18 kB
Markdown
# NAPI-Thread-Safe-Promise
[](https://badge.fury.io/js/napi_thread_safe_promise)
- [NAPI-Thread-Safe-Promise](#napi-thread-safe-promise)
- [Introduction](#introduction)
- [Usage](#usage)
- [Exception handling](#exception-handling)
- [Examples](#examples)
- [Async Promise Example (with macro)](#async-promise-example-with-macro)
- [Async Promise Example (without using macro)](#async-promise-example-without-using-macro)
- [JavaScript code for the code examples above](#javascript-code-for-the-code-examples-above)
- [Contribution](#contribution)
- [License](#license)
## Introduction
**NOTE**: This package assumes understanding of N-API
To be used in conjunction with the N-API module to call C++ code from JavaScript.
Allows the user to call thread safe promise functions such (resolve, reject) in the C++ code and return a promise to the javascript code.
## Usage
1. Install the package using node package manager:
```sh
npm install napi_thread_safe_promise
```
2. Reference this package's include directory in `binding.gyp`:
```gyp
'include_dirs': ["<!@(node -p \"require('napi_thread_safe_promise').include\")"],
```
3. Include the header in your code:
```C++
#include "promiseWrapper.h"
```
**Note:** Currently latest node version has bugs with regards to gyp so use the latest stable version (should be `v14.15.3` as of now)
### Exception handling
To have the ability for exceptions add the following to `binding.gyp`:
```gyp
'cflags!': [ '-fno-exceptions' ],
'cflags_cc!': [ '-fno-exceptions' ],
'xcode_settings': {
'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
'CLANG_CXX_LIBRARY': 'libc++',
'MACOSX_DEPLOYMENT_TARGET': '10.7',
},
'msvs_settings': {
'VCCLCompilerTool': { 'ExceptionHandling': 1 },
},
'conditions': [
['OS=="win"', { 'defines': [ '_HAS_EXCEPTIONS=1' ] }]
]
```
## Examples
### Async Promise Example (with macro)
```C++
Napi::Promise promiseFuncJS(const CallbackInfo& info)
{
// macro takes in info variable as input
return PROMISE(info, {
// now we can write our code here with access to the resolve and reject functions
// we can now take in resolve and reject function to our threaded function because they are thread safe
// note other variables we declared here may not be thread safe (ex. info variable is not thread safe)
std::thread([resolve, reject]() {
// we can pass strings to our resolve and reject functions
resolve("test");
// note secondary calls to resolve or reject will have no effect
resolve("test123");
}).detach();
});
}
```
**Note:** if we wish to pass json data to our resolve function we just pass in the json string to the function and parse it in the javascript code
> We can use a library like https://github.com/nlohmann/json and use the dump function to accomplish this
### Async Promise Example (without using macro)
```C++
Napi::Promise promiseFuncJS(const CallbackInfo& info) {
return promiseFuncWrapper(info.Env(),
[&info](resolveFunc resolve, rejectFunc reject) { // anonymous function passed to thread safe resolve and reject functions
// here we can write our threaded code
std::string arg1 = info[0].As<Napi::String>();
std::thread([resolve, reject, arg1]() {
reject(arg1);
}).detach();
}
);
}
```
### JavaScript code for the code examples above
```Javascript
promiseFuncJS(test)
.then(output => {
console.log(output);
})
.catch(err => {
console.error(err);
});
```
## Contribution
For contribution to this package, create a pull request and the maintainer will look into it.
## License
NAPI-Thread-Safe-Promise is licensed under BSD-3-Clause.