n-api: add napi_get_version #13207

mhdawson · 2017-05-24T21:01:28Z

Add napi_get_version function so that addons can
query the level of N-API supported.

Fixes: nodejs/abi-stable-node#231

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows [commit guidelines]

Affected core subsystem(s)

n-api

Add napi_get_version function so that addons can query the level of N-API supported. Fixes: nodejs/abi-stable-node#231

addaleax · 2017-05-24T21:03:24Z

doc/api/n-api.md

+
+### napi_get_version
+<!-- YAML
+added: v8.0.0


added: REPLACEME

addaleax · 2017-05-24T21:03:40Z

doc/api/n-api.md

+-->
+```C
+NAPI_EXTERN napi_status napi_get_version(napi_env env,
+                                        uint32_t* result);


The argument alignment is slightly off here

mhdawson · 2017-05-25T13:45:09Z

Thanks for the comments, push commit to address.

cjihrig · 2017-05-25T13:53:14Z

test/addons-napi/test_general/test.js

+
+// test version management funcitons
+// expected version is currently 1
+assert.strictEqual(test_general.testGetVersion(), 1);


Is this test going to need to be updated every time the napi version is bumped?

jasongin · 2017-05-25T16:21:29Z

@mhdawson I don't understand how this API can be very useful in practice, even after reading the doc added here.

Consider a native module that wants to use a function that was added in N-API v2. Even if that native module code calls napi_get_version() to check before invoking the new function, the native module will still fail to load on node versions with only N-API v1, due to unresolved external symbols. (I think? Maybe that is platform-dependent?) In that case, this scenario completely depends on back-porting "stubs" to older versions. But we know many applications do not always update to the latest patch version of their major release. And also, if we're backporting something, why wouldn't we backport the implementation rather than just stubs?

addaleax · 2017-05-25T22:16:33Z

@jasongin Fwiw, addons can use dlsym & its siblings in order to load symbols dynamically if they know that those aren’t available unconditionally. But yes, otherwise addons would just fail to load.

jasongin · 2017-05-25T22:22:14Z

addons can use dlsym & its siblings in order to load symbols dynamically if they know that those aren’t available unconditionally

Yes, we discussed this in the N-API sync meeting earlier today. That is a way module authors could use this napi_get_version() API to enable more complete backward-compatibility, without depending on back-ported stubs. It will require more work to be able to load and call such APIs, but that can potentially be hidden in the node-addon-api headers.

jasongin · 2017-05-25T22:36:50Z

doc/api/n-api.md

+`napi_get_version` to check which level of N-API is supported
+at run time. Based on the result of this check the addon can
+implement appropriate code paths when functions
+are, or are not, fully implemented. 


I would omit the mention of backporting stubs, since that wouldn't provide addon developers any real guarantees because many applications will not have the updates with the backported stubs. Instead, if addon developers desire backward compatibility with Node versions having older N-API versions, we should recommend dynamically loading APIs that might not be present, after checking the version.

I'd suggest changing this paragraph to something like this:

This API returns the highest N-API version supported by the Node.js runtime. N-API is planned to be additive such that newer releases of Node.js may support additional API functions. To allow an addon to use a newer API when it's available while providing a fallback behavior when it's not, first call `napi_get_version()` to determine if the API is available, then use `uv_dlsym()` to dynamically load a pointer to the function.

mhdawson · 2017-05-25T23:52:11Z

@jasongin pushed commit to address suggestion.

jasongin · 2017-05-26T00:10:18Z

doc/api/n-api.md

+newer releases of Node.js may support additional API functions.
+In order to allow an addon to use a newer function when running with
+versions of Node.js that support it, while providing
+fallback behaviour when runnign with Node.js versions that don't 


Typo: runnign

Also, do we prefer American or British spelling of "behaviour"?

mhdawson · 2017-05-26T17:40:22Z

Pushed commit to address remaining comments.
CI run: https://ci.nodejs.org/job/node-test-pull-request/8323/

mhdawson · 2017-05-26T20:35:43Z

OSX failure was unrelated to change being made. Opened this issue to track: #13248

Going to land.

mhdawson · 2017-05-26T21:07:37Z

Landed as d9ee297

Add napi_get_version function so that addons can query the level of N-API supported. PR-URL: #13207 Fixes: nodejs/abi-stable-node#231 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>

kunalspathak · 2017-05-31T17:54:11Z

src/node_api.cc

@@ -18,6 +18,8 @@
 #include "uv.h"
 #include "node_api.h"

+#define NAPI_VERSION  1


@mhdawson - Was there any reason this is not inside src/node_api.h instead?

mhdawson · 2017-05-31T18:10:04Z

I made it internal as it was only used by node_api.cc. Not sure if we want code doing compile time checks.

jasongin · 2017-05-31T18:47:55Z

We don't want to encourage people to do compile-time checks of the N-API version, because the runtime version could be different. I think it should stay internal-only.

Add napi_get_version function so that addons can query the level of N-API supported. PR-URL: nodejs#13207 Fixes: nodejs/abi-stable-node#231 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>

Add napi_get_version function so that addons can query the level of N-API supported. Backport-PR-URL: #19447 PR-URL: #13207 Fixes: nodejs/abi-stable-node#231 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>

n-api: add napi_get_version

a1c224c

Add napi_get_version function so that addons can query the level of N-API supported. Fixes: nodejs/abi-stable-node#231

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. node-api Issues and PRs related to the Node-API. labels May 24, 2017

addaleax approved these changes May 24, 2017

View reviewed changes

addaleax added the semver-minor PRs that contain new features and should be released in the next minor version. label May 24, 2017

squash: address comments

fbee2f5

cjihrig reviewed May 25, 2017

View reviewed changes

cjihrig approved these changes May 25, 2017

View reviewed changes

jasnell approved these changes May 25, 2017

View reviewed changes

jasongin reviewed May 25, 2017

View reviewed changes

squash: address comments

86cc570

jasongin reviewed May 26, 2017

View reviewed changes

jasongin approved these changes May 26, 2017

View reviewed changes

squash: address comments

fcb9f8b

mhdawson closed this May 26, 2017

jasnell mentioned this pull request May 28, 2017

8.0.0 Release Proposal #12220

Closed

kunalspathak reviewed May 31, 2017

View reviewed changes

mhdawson deleted the napi_version branch June 28, 2017 19:23

MylesBorins added the dont-land-on-v6.x label Jan 11, 2018

MylesBorins mentioned this pull request Apr 16, 2018

v6.14.2 proposal #19996

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

n-api: add napi_get_version #13207

n-api: add napi_get_version #13207

mhdawson commented May 24, 2017

addaleax May 24, 2017

addaleax May 24, 2017

mhdawson commented May 25, 2017

cjihrig May 25, 2017

jasongin commented May 25, 2017

addaleax commented May 25, 2017

jasongin commented May 25, 2017

jasongin May 25, 2017

mhdawson commented May 25, 2017

jasongin May 26, 2017

mhdawson commented May 26, 2017

mhdawson commented May 26, 2017

mhdawson commented May 26, 2017

kunalspathak May 31, 2017

mhdawson commented May 31, 2017 •

edited

jasongin commented May 31, 2017

n-api: add napi_get_version #13207

n-api: add napi_get_version #13207

Conversation

mhdawson commented May 24, 2017

Checklist

Affected core subsystem(s)

addaleax May 24, 2017

Choose a reason for hiding this comment

addaleax May 24, 2017

Choose a reason for hiding this comment

mhdawson commented May 25, 2017

cjihrig May 25, 2017

Choose a reason for hiding this comment

jasongin commented May 25, 2017

addaleax commented May 25, 2017

jasongin commented May 25, 2017

jasongin May 25, 2017

Choose a reason for hiding this comment

mhdawson commented May 25, 2017

jasongin May 26, 2017

Choose a reason for hiding this comment

mhdawson commented May 26, 2017

mhdawson commented May 26, 2017

mhdawson commented May 26, 2017

kunalspathak May 31, 2017

Choose a reason for hiding this comment

mhdawson commented May 31, 2017 • edited

jasongin commented May 31, 2017

mhdawson commented May 31, 2017 •

edited