Skip to content

Commit 09c7b71

Browse files
authored
Conditional support for C++ exceptions (#52)
Enable using the N-API C++ wrapper classes with or without C++ exceptions. See the updated `Napi::Error` class documentation for an overview of the developer experience. - Add a `NAPI_CPP_EXCEPTIONS` preprocessor symbol that is defined when C++ exceptions are enabled. - Add `Env::GetAndClearPendingException()` method. - Add `Value::IsEmpty()` method. - Update documentation on Error class to provide parallel explanation and examples for error-handling without C++ exceptions. - Update README to mention optional C++ exception support. - Define a `NAPI_THROW_IF_FAILED()` macro that throws either a C++ or JS exception depending on whether `NAPI_CPP_EXCEPTIONS` is defined. - Define a `details::WrapCallback()` helper function that catches C++ exceptions thrown from callbacks, only if `NAPI_CPP_EXCEPTIONS` is defined. - Update implementation of all methods to use `NAPI_THROW_IF_FAILED()` and `details::WrapCallback()` as appropriate. - Fix a bug in `Error::New()` when there was a pending exception but some different error status was reported by the last error info. - Update `test/binding.gyp` to build two separate modules, with and without C++ exceptions enabled. - Update test JS code to run the same tests against both modules. - Update test C++ code to throw JS exceptions (to be compatible with both modes). - Add some additional test cases to verify expected exceptions are observed from JS regardless of whether C++ exceptions are enabled or not. - Change CI config to ignore failures on nightly builds.
1 parent a1a1076 commit 09c7b71

25 files changed

+946
-583
lines changed

.editorconfig

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
trim_trailing_whitespace = true
6+
insert_final_newline = true
7+
indent_style = space
8+
indent_size = 2

.travis.yml

+6
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ env:
1919
- NODEJS_VERSION=chakracore-nightly
2020
matrix:
2121
fast_finish: true
22+
allow_failures:
23+
- env: NODEJS_VERSION=nightly
24+
- env: NODEJS_VERSION=chakracore-nightly
2225
sudo: false
2326
cache:
2427
directories:
@@ -50,6 +53,9 @@ before_install:
5053
install:
5154
- npm install $NPMOPT
5255
script:
56+
# Travis CI sets NVM_NODEJS_ORG_MIRROR, but it makes node-gyp fail to download headers for nightly builds.
57+
- unset NVM_NODEJS_ORG_MIRROR
58+
5359
- npm test $NPMOPT
5460
after_success:
5561
- cpp-coveralls --gcov-options '\-lp' --build-root test/build --exclude test

README.md

+10-3
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,12 @@ To use N-API in a native module:
2626
'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
2727
```
2828

29-
3. Ensure C++ exceptions are enabled in `binding.gyp`.
30-
The N-API C++ wrapper classes use exceptions for error-handling;
31-
the base ABI-stable C APIs do not.
29+
3. Decide whether the package will enable C++ exceptions in the N-API wrapper.
30+
The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
31+
N-API C++ wrapper classes may _optionally_
32+
[integrate C++ and JavaScript exception-handling
33+
](https://nodejs.github.io/node-addon-api/class_napi_1_1_error.html).
34+
To enable that capability, C++ exceptions must be enabled in `binding.gyp`:
3235
```gyp
3336
'cflags!': [ '-fno-exceptions' ],
3437
'cflags_cc!': [ '-fno-exceptions' ],
@@ -41,6 +44,10 @@ To use N-API in a native module:
4144
'VCCLCompilerTool': { 'ExceptionHandling': 1 },
4245
},
4346
```
47+
Alternatively, disable use of C++ exceptions in N-API:
48+
```gyp
49+
'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
50+
```
4451

4552
4. Include `napi.h` in the native module code.
4653
To ensure only ABI-stable APIs are used, DO NOT include

appveyor.yml

+6
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@ environment:
99
- NODEJS_VERSION: nightly
1010
- NODEJS_VERSION: chakracore-nightly
1111

12+
matrix:
13+
fast_finish: true
14+
allow_failures:
15+
- NODEJS_VERSION: nightly
16+
- NODEJS_VERSION: chakracore-nightly
17+
1218
platform:
1319
- x86
1420
- x64

0 commit comments

Comments
 (0)