Skip to content

Commit

Permalink
n-api: enable napi_wrap() to work with any object
Browse files Browse the repository at this point in the history
Previously, napi_wrap() would only work with objects created from a
constructor returned by napi_define_class(). While the N-API team
was aware of this limitation, it was not clearly documented and is
likely to cause confusion anyway. It's much simpler if addons are
allowed to use any JS object. Also, the specific behavior of the
limitation is difficult to reimplement on other VMs that work
differently from V8.

V8 requires object internal fields to be declared on the object
prototype (which napi_define_class() used to do). Since it's too
late to modify the object prototype by the time napi_wrap() is
called, napi_wrap() now inserts a new object (with the internal
field) into the supplied object's prototype chain. Then it can be
retrieved from there later by napi_unwrap().

This change also includes improvements to the documentation for
napi_create_external(), partly to explain how it is different from
napi_wrap().

PR-URL: #13250
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
jasongin authored and jasnell committed Jun 5, 2017
1 parent b8b0bfb commit a95f080
Show file tree
Hide file tree
Showing 4 changed files with 159 additions and 65 deletions.
57 changes: 36 additions & 21 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -1059,20 +1059,24 @@ napi_status napi_create_external(napi_env env,
```

- `[in] env`: The environment that the API is invoked under.
- `[in] data`: Raw pointer to the external data being wrapped.
- `[in] finalize_cb`: Optional callback to call when the wrapped object
- `[in] data`: Raw pointer to the external data.
- `[in] finalize_cb`: Optional callback to call when the external value
is being collected.
- `[in] finalize_hint`: Optional hint to pass to the finalize callback
during collection.
- `[out] result`: A `napi_value` representing an external object.
- `[out] result`: A `napi_value` representing an external value.

Returns `napi_ok` if the API succeeded.

This API allocates a JavaScript object with external data attached to it.
This is used to wrap native objects and project them into JavaScript.
The API allows the caller to pass in a finalize callback, in case the
underlying native resource needs to be cleaned up when the wrapper
JavaScript object gets collected.
This API allocates a JavaScript value with external data attached to it. This
is used to pass external data through JavaScript code, so it can be retrieved
later by native code. The API allows the caller to pass in a finalize callback,
in case the underlying native resource needs to be cleaned up when the external
JavaScript value gets collected.

*Note*: The created value is not an object, and therefore does not support
additional properties. It is considered a distinct value type: calling
`napi_typeof()` with an external value yields `napi_external`.

#### napi_create_external_arraybuffer
<!-- YAML
Expand Down Expand Up @@ -1364,7 +1368,8 @@ Returns `napi_ok` if the API succeeded.
This API is used to retrieve the underlying data buffer of an ArrayBuffer and
its length.
WARNING: Use caution while using this API. The lifetime of the underlying data
*WARNING*: Use caution while using this API. The lifetime of the underlying data
buffer is managed by the ArrayBuffer even after it's returned. A
possible safe way to use this API is in conjunction with [`napi_create_reference`][],
which can be used to guarantee control over the lifetime of the
Expand All @@ -1391,7 +1396,8 @@ Returns `napi_ok` if the API succeeded.

This API is used to retrieve the underlying data buffer of a `node::Buffer`
and it's length.
Warning: Use caution while using this API since the underlying data buffer's

*Warning*: Use caution while using this API since the underlying data buffer's
lifetime is not guaranteed if it's managed by the VM.

#### *napi_get_prototype*
Expand Down Expand Up @@ -1438,7 +1444,8 @@ to start projecting the TypedArray.
Returns `napi_ok` if the API succeeded.

This API returns various properties of a typed array.
Warning: Use caution while using this API since the underlying data buffer

*Warning*: Use caution while using this API since the underlying data buffer
is managed by the VM

#### *napi_get_value_bool*
Expand All @@ -1457,8 +1464,8 @@ Boolean.
Returns `napi_ok` if the API succeeded. If a non-boolean `napi_value` is
passed in it returns `napi_boolean_expected`.
This API returns C boolean primitive equivalent of the given JavaScript
Boolea
This API returns the C boolean primitive equivalent of the given JavaScript
Boolean.
#### *napi_get_value_double*
<!-- YAML
Expand Down Expand Up @@ -1493,14 +1500,14 @@ napi_status napi_get_value_external(napi_env env,
```
- `[in] env`: The environment that the API is invoked under.
- `[in] value`: `napi_value` representing JavaScript External value.
- `[out] result`: Pointer to the data wrapped by the JavaScript External value.
- `[in] value`: `napi_value` representing JavaScript external value.
- `[out] result`: Pointer to the data wrapped by the JavaScript external value.
Returns `napi_ok` if the API succeeded. If a non-external `napi_value` is
passed in it returns `napi_invalid_arg`.
This API returns the pointer to the data wrapped by the JavaScript
External value
This API retrieves the external data pointer that was previously passed to
`napi_create_external()`.
#### *napi_get_value_int32*
<!-- YAML
Expand Down Expand Up @@ -2770,6 +2777,7 @@ napi_status napi_wrap(napi_env env,
Returns `napi_ok` if the API succeeded.
Wraps a native instance in JavaScript object of the corresponding type.
The native instance can be retrieved later using `napi_unwrap()`.
When JavaScript code invokes a constructor for a class that was defined using
`napi_define_class()`, the `napi_callback` for the constructor is invoked.
Expand All @@ -2787,12 +2795,16 @@ The optional returned reference is initially a weak reference, meaning it
has a reference count of 0. Typically this reference count would be incremented
temporarily during async operations that require the instance to remain valid.
Caution: The optional returned reference (if obtained) should be deleted via
[`napi_delete_reference`][] ONLY in response to the finalize callback invocation.
(If it is deleted before then, then the finalize callback may never be
invoked.) Therefore when obtaining a reference a finalize callback is also
*Caution*: The optional returned reference (if obtained) should be deleted via
[`napi_delete_reference`][] ONLY in response to the finalize callback
invocation. (If it is deleted before then, then the finalize callback may never
be invoked.) Therefore, when obtaining a reference a finalize callback is also
required in order to enable correct proper of the reference.
*Note*: This API may modify the prototype chain of the wrapper object.
Afterward, additional manipulation of the wrapper's prototype chain may cause
`napi_unwrap()` to fail.
### *napi_unwrap*
<!-- YAML
added: v8.0.0
Expand All @@ -2809,6 +2821,9 @@ napi_status napi_unwrap(napi_env env,

Returns `napi_ok` if the API succeeded.

Retrieves a native instance that was previously wrapped in a JavaScript
object using `napi_wrap()`.

When JavaScript code invokes a method or property accessor on the class, the
corresponding `napi_callback` is invoked. If the callback is for an instance
method or accessor, then the `this` argument to the callback is the wrapper
Expand Down
42 changes: 28 additions & 14 deletions src/node_api.cc
Original file line number Diff line number Diff line change
Expand Up @@ -819,9 +819,6 @@ napi_status napi_define_class(napi_env env,
v8::Local<v8::FunctionTemplate> tpl = v8::FunctionTemplate::New(
isolate, v8impl::FunctionCallbackWrapper::Invoke, cbdata);

// we need an internal field to stash the wrapped object
tpl->InstanceTemplate()->SetInternalFieldCount(1);

v8::Local<v8::String> name_string;
CHECK_NEW_FROM_UTF8(env, name_string, utf8name);
tpl->SetClassName(name_string);
Expand Down Expand Up @@ -1950,14 +1947,24 @@ napi_status napi_wrap(napi_env env,
CHECK_ARG(env, js_object);

v8::Isolate* isolate = env->isolate;
v8::Local<v8::Object> obj =
v8impl::V8LocalValueFromJsValue(js_object).As<v8::Object>();
v8::Local<v8::Context> context = isolate->GetCurrentContext();

// Only objects that were created from a NAPI constructor's prototype
// via napi_define_class() can be (un)wrapped.
RETURN_STATUS_IF_FALSE(env, obj->InternalFieldCount() > 0, napi_invalid_arg);
v8::Local<v8::Value> value = v8impl::V8LocalValueFromJsValue(js_object);
RETURN_STATUS_IF_FALSE(env, value->IsObject(), napi_invalid_arg);
v8::Local<v8::Object> obj = value.As<v8::Object>();

// Create a wrapper object with an internal field to hold the wrapped pointer.
v8::Local<v8::ObjectTemplate> wrapperTemplate =
v8::ObjectTemplate::New(isolate);
wrapperTemplate->SetInternalFieldCount(1);
v8::Local<v8::Object> wrapper =
wrapperTemplate->NewInstance(context).ToLocalChecked();
wrapper->SetInternalField(0, v8::External::New(isolate, native_object));

obj->SetInternalField(0, v8::External::New(isolate, native_object));
// Insert the wrapper into the object's prototype chain.
v8::Local<v8::Value> proto = obj->GetPrototype();
wrapper->SetPrototype(proto);
obj->SetPrototype(wrapper);

if (result != nullptr) {
// The returned reference should be deleted via napi_delete_reference()
Expand Down Expand Up @@ -1988,11 +1995,18 @@ napi_status napi_unwrap(napi_env env, napi_value js_object, void** result) {
RETURN_STATUS_IF_FALSE(env, value->IsObject(), napi_invalid_arg);
v8::Local<v8::Object> obj = value.As<v8::Object>();

// Only objects that were created from a NAPI constructor's prototype
// via napi_define_class() can be (un)wrapped.
RETURN_STATUS_IF_FALSE(env, obj->InternalFieldCount() > 0, napi_invalid_arg);

v8::Local<v8::Value> unwrappedValue = obj->GetInternalField(0);
// Search the object's prototype chain for the wrapper with an internal field.
// Usually the wrapper would be the first in the chain, but it is OK for
// other objects to be inserted in the prototype chain.
v8::Local<v8::Object> wrapper = obj;
do {
v8::Local<v8::Value> proto = wrapper->GetPrototype();
RETURN_STATUS_IF_FALSE(
env, !proto.IsEmpty() && proto->IsObject(), napi_invalid_arg);
wrapper = proto.As<v8::Object>();
} while (wrapper->InternalFieldCount() != 1);

v8::Local<v8::Value> unwrappedValue = wrapper->GetInternalField(0);
RETURN_STATUS_IF_FALSE(env, unwrappedValue->IsExternal(), napi_invalid_arg);

*result = unwrappedValue.As<v8::External>()->Value();
Expand Down
98 changes: 68 additions & 30 deletions test/addons-napi/test_object/test.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,35 +31,73 @@ assert(test_object.Has(newObject, 'test_number'));
assert.strictEqual(newObject.test_number, 987654321);
assert.strictEqual(newObject.test_string, 'test string');

// test_object.Inflate increases all properties by 1
const cube = {
x: 10,
y: 10,
z: 10
};
{
// test_object.Inflate increases all properties by 1
const cube = {
x: 10,
y: 10,
z: 10
};

assert.deepStrictEqual(test_object.Inflate(cube), {x: 11, y: 11, z: 11});
assert.deepStrictEqual(test_object.Inflate(cube), {x: 12, y: 12, z: 12});
assert.deepStrictEqual(test_object.Inflate(cube), {x: 13, y: 13, z: 13});
cube.t = 13;
assert.deepStrictEqual(test_object.Inflate(cube), {x: 14, y: 14, z: 14, t: 14});

const sym1 = Symbol('1');
const sym2 = Symbol('2');
const sym3 = Symbol('3');
const sym4 = Symbol('4');
const object2 = {
[sym1]: '@@iterator',
[sym2]: sym3
};
assert.deepStrictEqual(test_object.Inflate(cube), {x: 11, y: 11, z: 11});
assert.deepStrictEqual(test_object.Inflate(cube), {x: 12, y: 12, z: 12});
assert.deepStrictEqual(test_object.Inflate(cube), {x: 13, y: 13, z: 13});
cube.t = 13;
assert.deepStrictEqual(
test_object.Inflate(cube), {x: 14, y: 14, z: 14, t: 14});

const sym1 = Symbol('1');
const sym2 = Symbol('2');
const sym3 = Symbol('3');
const sym4 = Symbol('4');
const object2 = {
[sym1]: '@@iterator',
[sym2]: sym3
};

assert(test_object.Has(object2, sym1));
assert(test_object.Has(object2, sym2));
assert.strictEqual(test_object.Get(object2, sym1), '@@iterator');
assert.strictEqual(test_object.Get(object2, sym2), sym3);
assert(test_object.Set(object2, 'string', 'value'));
assert(test_object.Set(object2, sym4, 123));
assert(test_object.Has(object2, 'string'));
assert(test_object.Has(object2, sym4));
assert.strictEqual(test_object.Get(object2, 'string'), 'value');
assert.strictEqual(test_object.Get(object2, sym4), 123);
}

{
// Wrap a pointer in a JS object, then verify the pointer can be unwrapped.
const wrapper = {};
test_object.Wrap(wrapper);

assert(test_object.Unwrap(wrapper));
}

{
// Verify that wrapping doesn't break an object's prototype chain.
const wrapper = {};
const protoA = { protoA: true };
Object.setPrototypeOf(wrapper, protoA);
test_object.Wrap(wrapper);

assert(test_object.Unwrap(wrapper));
assert(wrapper.protoA);
}

{
// Verify the pointer can be unwrapped after inserting in the prototype chain.
const wrapper = {};
const protoA = { protoA: true };
Object.setPrototypeOf(wrapper, protoA);
test_object.Wrap(wrapper);

const protoB = { protoB: true };
Object.setPrototypeOf(protoB, Object.getPrototypeOf(wrapper));
Object.setPrototypeOf(wrapper, protoB);

assert(test_object.Has(object2, sym1));
assert(test_object.Has(object2, sym2));
assert.strictEqual(test_object.Get(object2, sym1), '@@iterator');
assert.strictEqual(test_object.Get(object2, sym2), sym3);
assert(test_object.Set(object2, 'string', 'value'));
assert(test_object.Set(object2, sym4, 123));
assert(test_object.Has(object2, 'string'));
assert(test_object.Has(object2, sym4));
assert.strictEqual(test_object.Get(object2, 'string'), 'value');
assert.strictEqual(test_object.Get(object2, sym4), 123);
assert(test_object.Unwrap(wrapper));
assert(wrapper.protoA, true);
assert(wrapper.protoB, true);
}
27 changes: 27 additions & 0 deletions test/addons-napi/test_object/test_object.c
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#include <node_api.h>
#include "../common.h"
#include <string.h>
#include <stdlib.h>

napi_value Get(napi_env env, napi_callback_info info) {
size_t argc = 2;
Expand Down Expand Up @@ -138,13 +139,39 @@ napi_value Inflate(napi_env env, napi_callback_info info) {
return obj;
}

napi_value Wrap(napi_env env, napi_callback_info info) {
size_t argc = 1;
napi_value arg;
NAPI_CALL(env, napi_get_cb_info(env, info, &argc, &arg, NULL, NULL));

int32_t* data = malloc(sizeof(int32_t));
*data = 3;
NAPI_CALL(env, napi_wrap(env, arg, data, NULL, NULL, NULL));
return NULL;
}

napi_value Unwrap(napi_env env, napi_callback_info info) {
size_t argc = 1;
napi_value arg;
NAPI_CALL(env, napi_get_cb_info(env, info, &argc, &arg, NULL, NULL));

int32_t* data;
NAPI_CALL(env, napi_unwrap(env, arg, &data));

napi_value result;
NAPI_CALL(env, napi_get_boolean(env, data != NULL && *data == 3, &result));
return result;
}

void Init(napi_env env, napi_value exports, napi_value module, void* priv) {
napi_property_descriptor descriptors[] = {
DECLARE_NAPI_PROPERTY("Get", Get),
DECLARE_NAPI_PROPERTY("Set", Set),
DECLARE_NAPI_PROPERTY("Has", Has),
DECLARE_NAPI_PROPERTY("New", New),
DECLARE_NAPI_PROPERTY("Inflate", Inflate),
DECLARE_NAPI_PROPERTY("Wrap", Wrap),
DECLARE_NAPI_PROPERTY("Unwrap", Unwrap),
};

NAPI_CALL_RETURN_VOID(env, napi_define_properties(
Expand Down

0 comments on commit a95f080

Please sign in to comment.