Add a utility functions for addons to use when they need
a reference to the current event loop.
While the libuv API is not directly part of N-API, it
provides a quite stable C API as well, and is tightly
integrated with Node itself.
As a particular use case, without access to the event loop
it is hard to do something interesting from inside a N-API
finalizer function, since calls into JS and therefore virtually
all other N-API functions are not allowed.
PR-URL: https://github.com/nodejs/node/pull/17109
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
* namespaced functions such as v8impl::JsHandleScopeFromV8HandleScope
become part of Node's public symbols unless they are declared static.
* the class uvimpl::Work needs to be enclosed in an anonymous namespace
else it, too becomes part of Node's public symbols.
* remove references to EXTERNAL_NAPI.
PR-URL: https://github.com/nodejs/node/pull/16234
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
These changes are necessary in order to retain source compatibility
with older versions of node.
The removal of `module_version` from `napi_module_register()` is
reverted from the flag removal PR, because it should not have been a
part of it.
`CallbackWrapper::NewTarget()` is renamed to
`CallbackWrapper::GetNewTarget()` to distinguish it from V8's native
method, thus allowing for a macro which reduces `NewTarget()` to
`This()` on V8 versions where it was not yet available.
`AsyncResource` is constructed with a C string rather than a V8 string
because the former is available on all versions of node.
PR-URL: https://github.com/nodejs/node/pull/16102
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>
n-api uses size_t for the size of strings when specifying
string lengths. V8 only supports a size of int. Add
a check so that an error will be returned if the user
passes in a string with a size larger than will fit into
an int.
PR-URL: https://github.com/nodejs/node/pull/15611
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
- Add napi_async_context opaque pointer type.
(If needed, we could later add APIs for getting the async IDs
out of this context.)
- Add napi_async_init() and napi_async_destroy() APIs.
- Add async_context parameter to napi_make_callback().
- Add code and checks to test_make_callback to validate async context
APIs by checking async hooks are called with correct context.
- Update API documentation.
PR-URL: https://github.com/nodejs/node/pull/15189
Fixes: https://github.com/nodejs/node/issues/13254
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
`node_internals.h` already includes the most common headers,
so double includes can be avoided in a lot of cases. Also don’t include
`node_internals.h` from `node.h` implicitly anymore, as that is mostly
unnecessary.
PR-URL: https://github.com/nodejs/node/pull/14697
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
The binding testing napi_wrap() creates references to primitives passed
into the binding in its second parameter. This is unnecessary and not
at all the point of the test. Additionally, creating persistent
references to primitive values may not be supported by all VMs, since
primitives are best persisted in their native form.
Instead, the point of the test is to make sure that the finalize
callback gets called when it should get called, that it gets called
with the correct pointer, and that it does not get called when it
should not get called. Creating persistent references is not necessary
for verifying this.
PR-URL: https://github.com/nodejs/node/pull/15289
Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Re: https://github.com/nodejs/node-chakracore/issues/380
Promise is implemented as a pair of objects. `napi_create_promise()`
returns both a JavaScript promise and a newly allocated "deferred" in
its out-params. The deferred is linked to the promise such that the
deferred can be passed to `napi_resolve_deferred()` or
`napi_reject_deferred()` to reject/resolve the promise.
`napi_is_promise()` can be used to check if a `napi_value` is a native
promise - that is, a promise created by the underlying engine, rather
than a pure JS implementation of a promise.
PR-URL: https://github.com/nodejs/node/pull/14365
Fixes: https://github.com/nodejs/abi-stable-node/issues/242
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Calling napi_wrap() twice on the same object has the result of returning
napi_invalid_arg on the second call. However, sometimes it is necessary
to replace the native pointer associated with a given object. This new
API allows one to remove an existing pointer, returning the object to
its pristine, non-wrapped state.
PR-URL: https://github.com/nodejs/node/pull/14658
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Fixes: https://github.com/nodejs/abi-stable-node/issues/266
- Add separate APIs for creating different kinds of numbers,
because creating a V8 number value from an integer is faster
than creating one from a double.
- When getting number values, avoid getting the current context
because the context will not actually be used and is expensive
to obtain.
- When creating values, don't use v8::TryCatch (NAPI_PREAMBLE),
because these functions have no possibility of executing JS code.
Refs: https://github.com/nodejs/node/issues/14379
PR-URL: https://github.com/nodejs/node/pull/14573
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Use a stronger criterion to identify objects in the prototype chain that store
pointers to native data that were added by previous calls to `napi_wrap()`.
Whereas the old criterion for identifying `napi_wrap()`-injected prototype
chain objects was to consider an object with an internal field
count of 1 to be such an object, the new criterion is to consider an object
with an internal field count of 2 such that the second field holds a
`v8::External` which itself contains a pointer to a global static string unique
to N-API to be a `napi_wrap()`-injected prototype chain object.
This greatly reduces the possibility of returning a pointer that was not
previously added with `napi_wrap()`, and it allows us to recognize that an
object has already undergone `napi_wrap()` and we can thus prevent a chain of
wrappers only the first of which is accessible from appearing in the prototype
chain, as would be the result of multiple calls to `napi_wrap()` using the same
object.
PR-URL: https://github.com/nodejs/node/pull/13872
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Fixes the following deprecation warning:
../src/node_api.cc:2020:30: warning: 'bool
v8::Object::SetPrototype(v8::Local<v8::Value>)' is deprecated: Use
maybe version [-Wdeprecated-declarations]
wrapper->SetPrototype(proto);
../src/node_api.cc:2021:28: warning: 'bool
v8::Object::SetPrototype(v8::Local<v8::Value>)' is deprecated: Use
maybe version [-Wdeprecated-declarations]
obj->SetPrototype(wrapper);
PR-URL: https://github.com/nodejs/node/pull/14053
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
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: https://github.com/nodejs/node/pull/13250
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Unlike most N-API functions, `napi_get_last_error_info()` should not
clear the last error code when successful, because a pointer to (not
a copy of) the error info structure is returned via an out parameter.
PR-URL: https://github.com/nodejs/node/pull/13087
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
- Create a handle scope before invoking the async completion
callback, because it is basically always needed, easy for user
code to forget, and this makes it more consistent with ordinary
N-API function callbacks.
- Check for an unhandled JS exception after invoking an async
completion callback, and report it via `node::FatalException()`.
- Add a corresponding test case for an exception in async callback.
Previously, any unhandled JS exception thrown from a
`napi_async_complete_callback` would be silently ignored. Among other
things this meant assertions in some test cases could be undetected.
PR-URL: https://github.com/nodejs/node/pull/12838
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
These APIs do not need a try-catch around their body, because no
exceptions are thrown in their implementation:
- `napi_is_array()`
- `napi_get_value_string_latin1()`
- `napi_get_value_string_utf8()`
- `napi_get_value_string_utf16()`
- `napi_get_value_external()`
- `napi_is_buffer()`
- `napi_is_arraybuffer()`
- `napi_get_arraybuffer_info()`
- `napi_is_typedarray()`
- `napi_get_typedarray_info()`
Fixes: https://github.com/nodejs/abi-stable-node/issues/238
PR-URL: https://github.com/nodejs/node/pull/12705
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Background: To enable N-API support for node versions back to v4, the
N-API code can also be built as an external addon. To make maintenance
easier, a single codebase needs to support both built-in and external
scenarios, along with Node versions >= 4 (and corresponding V8
versions).
This change includes several minor fixes to avoid using node
internal APIs and support older V8 versions:
- Expand node::arraysize
- In the CHECK_ENV() macro, return an error code instead of calling
node::FatalError(). This is more consistent with how other invalid
arguments to N-API functions are handled.
- In v8impl::SetterCallbackWrapper::SetReturnValue(), do nothing
instead of calling node::FatalError(). This is more consistent
with JavaScript setter callbacks, where any returned value is
silently ignored.
- When queueing async work items, get the uv default loop instead of
getting the loop from node::Environment::GetCurrent(). Currently
that returns the same loop anyway. If/when node supports multiple
environments, it should have a public API for getting the
environment & event loop, and we can update this implementation
then.
- Use v8::Maybe::FromJust() instead of the newer alias ToChecked()
PR-URL: https://github.com/nodejs/node/pull/12674
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
N-API is somewhat strict about blocking calls to many APIs while there
is a pending exception. The NAPI_PREAMBLE macro at the beginning of
many API implementations checks for a pending exception. However, a
subset of the APIs (which don't call back into JavaScript) still need
to work while in a pending-exception state. This changes the reference
APIs (equivalent to v8::Persistent) and handle scope APIs so that they
can be used for cleanup up while an exception is pending.
We may decide to similarly enable a few other APIs later, (which would
be a non-breaking change) but we know at least these are needed now
to unblock some specific scenarios.
Fixes: https://github.com/nodejs/abi-stable-node/issues/122
Fixes: https://github.com/nodejs/abi-stable-node/issues/228
PR-URL: https://github.com/nodejs/node/pull/12524
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
We left out null-checks for many of the parameters passed to our APIs.
In particular, arguments of type `napi_value` were often accepted
without a null-check, even though they should never be null.
Additionally, many APIs simply returned `napi_ok` on success. This
leaves in place an error that may have occurred in a previous N-API
call. Others (those which perform `NAPI_PREAMBLE(env)` at the top)
OTOH explicitly clear the last error before proceeding. With this
modification all APIs explicitly clear the last error on success.
Fixes: https://github.com/nodejs/abi-stable-node/issues/227
PR-URL: https://github.com/nodejs/node/pull/12539
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
This API doesn't serve much purpose, and is only likely to cause
confusion and bugs. The intention was that this would return the
number of characters in a string independent of encoding, but
that's not generally useful. In almost all cases, one of the
encoding-specific napi_get_value_string_* APIs is more correct.
(Pass a null buffer if only the encoded length is desired.)
Anyway the current implementation of napi_get_value_string_length()
is technically wrong: it returns the number of 2-byte code units of
the UTF-16 encoding, but there are actually some characters that
are encoded as two UTF-16 code units.
Note the JavaScript String.prototype.length property returns the
number of UTF-16 code units, which may be different from the number
of characters. So, getting the true character count is not common
with JavaScript, and is probably best left to specialized
internationalization libraries.
PR-URL: https://github.com/nodejs/node/pull/12496
Fixes: https://github.com/nodejs/abi-stable-node/issues/226
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Anna Henningsen