Repository navigation
What are the semantics / guarantees of a napi_value? #131
Description
In particular, are there any assumptions about whether a napi_value is necessarily a reference to an object, or potentially a value in and of itself?
I ask this as someone implementing part of napi for chakracore: some chakracore values exposed through the native interface are primitive values, e.g. tagged integers. In general this is not observable, but when implementing the napi_create_reference API we can't really create a weak reference to such a primitive value. Is the expectation that all napi_values may have references, weak or otherwise, and thus we should be boxing all values returned from the chakracore native API?
Activity
gabrielschulhof commentedon Sep 7, 2017
A
napi_valueis a reference to a JavaScript value that is valid from the time control passes from the engine into N-API until the time that control passes from N-API back to the engine. This happens in three places (that I can think of):0. During module initialization
0. When a native binding gets called from JS
0. When a callback that wishes to make use of the engine gets called from the event loop
In the first two cases, a handle scope which keeps
napi_values alive is created by the engine. In the last case, a handle scope needs to be explicitly created in the callback so that it may then call into the engine.Semantically, I believe that all values may have persistent references. Practically, however, it is almost always object, functions, and externals that end up having such references. After all, it makes little sense to persistently refer to the number 42, or to the string "motor bike".
I think one course of action would be to introduce a difference in behaviour between N-API/V8 and N-API/ChakraCore whereby
napi_create_reference()returnsnapi_invalid_argif thenapi_valuepassed in is not a function, object, or external. It will at least show us if anybody out there is making persistent references to something other than those three types of values.MSLaguana commentedon Sep 7, 2017
Thanks for the explanation of the intent of
napi_value!That approach sounds reasonable to me, except that the reason I came across this case is because it is hit in one of node's tests: https://github.com/nodejs/node/blob/master/test/addons-napi/test_general/test.js#L72 passes a number
25to a napi module which tries to create a reference to the number https://github.com/nodejs/node/blob/master/test/addons-napi/test_general/test_general.c#L165gabrielschulhof commentedon Sep 7, 2017
gabrielschulhof commentedon Sep 7, 2017
mhdawson commentedon Dec 7, 2020
I think the original question was answered so closing out. Let us know if that is not the right thing to do.