Skip to content

Commit

Permalink
doc: update js-native-api example
Browse files Browse the repository at this point in the history
Update example that shows how to separate N-API code which is not
Node.js-specific from code which defines a Node.js N-API addon. In its
existing state the example uses the pattern

```C
assert(napi_*() == napi_ok);
```

However, this would result in no N-API calls when building with
`-DNDEBUG`.

This change moves away from assert and uses a macro `NAPI_CALL()` which
throws the string corresponding to the non-`napi_ok` status as a JS
exception and short-circuits the binding by returning `NULL`.

PR-URL: #28657
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
  • Loading branch information
Gabriel Schulhof authored and targos committed Jul 20, 2019
1 parent 8ddf86b commit 4321cb2
Showing 1 changed file with 44 additions and 14 deletions.
58 changes: 44 additions & 14 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,33 +192,63 @@ napi_value create_addon(napi_env env);
```C
// addon.c
#include "addon.h"

#define NAPI_CALL(env, call) \
do { \
napi_status status = (call); \
if (status != napi_ok) { \
const napi_extended_error_info* error_info = NULL; \
napi_get_last_error_info((env), &error_info); \
bool is_pending; \
napi_is_exception_pending((env), &is_pending); \
if (!is_pending) { \
const char* message = (error_info->error_message == NULL) \
? "empty error message" \
: error_info->error_message; \
napi_throw_error((env), NULL, message); \
return NULL; \
} \
} \
} while(0)

static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Do something useful.
return NULL;
}

napi_value create_addon(napi_env env) {
napi_value result;
assert(napi_create_object(env, &result) == napi_ok);
NAPI_CALL(env, napi_create_object(env, &result));

napi_value exported_function;
assert(napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function) == napi_ok);
assert(napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function) == napi_ok);
NAPI_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));

NAPI_CALL(env, napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function));

return result;
}
```

```C
// addon_node.c
#include <node_api.h>
#include "addon.h"

static napi_value Init(napi_env env, napi_value exports) {
NAPI_MODULE_INIT() {
// This function body is expected to return a `napi_value`.
// The variables `napi_env env` and `napi_value exports` may be used within
// the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
return create_addon(env);
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
```

## Basic N-API Data Types
Expand Down

0 comments on commit 4321cb2

Please sign in to comment.