delta/node-new.git/src/node_api.cc, branch pull-request-doc-updates

src: move C++ binding/addon related code into node_binding{.h, .cc}

2018-12-01T04:14:24+00:00

This patch:

- Moves the C++ binding/addon related code out of
  node_internals.h/node.cc and into dedicated files
  node_binding.h/node_binding.cc, and only puts the code resued
  by other files into the header.
- Introduce a node::binding namespace so that code exposed to
  other files can be easily recognized.

PR-URL: https://github.com/nodejs/node/pull/24701
Reviewed-By: Ben Noordhuis 
Reviewed-By: Richard Lau

src: factor out Node.js-agnostic N-APIs

2018-11-17T22:38:51+00:00

Split the Node.js ECMAScript API (N-EAPI?) into its own header and
implementation files. The motivation is that the ECMAScript API stand
on its own so it might be embedded separately, implementation and all.

Portions of the implementation used by both files are stored in
`node_api_impl.h`.

The checked boxes below indicate that the given API remains in
`node_api.h`, whereas the lack of a checkbox indicates that the API was
moved to `node_ecma_api.h`.

* [x] NAPI_MODULE
* [x] NAPI_MODULE_INIT
* [x] napi_acquire_threadsafe_function
* [x] napi_add_env_cleanup_hook
* [x] napi_async_destroy
* [x] napi_async_init
* [x] napi_call_threadsafe_function
* [x] napi_cancel_async_work
* [x] napi_close_callback_scope
* [x] napi_create_async_work
* [x] napi_create_buffer
* [x] napi_create_buffer_copy
* [x] napi_create_external_buffer
* [x] napi_create_threadsafe_function
* [x] napi_delete_async_work
* [x] napi_fatal_error
* [x] napi_fatal_exception
* [x] napi_get_buffer_info
* [x] napi_get_node_version
* [x] napi_get_threadsafe_function_context
* [x] napi_get_uv_event_loop
* [x] napi_is_buffer
* [x] napi_make_callback
* [x] napi_module_register
* [x] napi_open_callback_scope
* [x] napi_queue_async_work
* [x] napi_ref_threadsafe_function
* [x] napi_release_threadsafe_function
* [x] napi_remove_env_cleanup_hook
* [x] napi_unref_threadsafe_function
* [ ] napi_add_finalizer
* [ ] napi_adjust_external_memory
* [ ] napi_call_function
* [ ] napi_close_escapable_handle_scope
* [ ] napi_close_handle_scope
* [ ] napi_coerce_to_bool
* [ ] napi_coerce_to_number
* [ ] napi_coerce_to_object
* [ ] napi_coerce_to_string
* [ ] napi_create_array
* [ ] napi_create_arraybuffer
* [ ] napi_create_array_with_length
* [ ] napi_create_bigint_int64
* [ ] napi_create_bigint_uint64
* [ ] napi_create_bigint_words
* [ ] napi_create_dataview
* [ ] napi_create_double
* [ ] napi_create_error
* [ ] napi_create_external
* [ ] napi_create_external_arraybuffer
* [ ] napi_create_function
* [ ] napi_create_int32
* [ ] napi_create_int64
* [ ] napi_create_object
* [ ] napi_create_promise
* [ ] napi_create_range_error
* [ ] napi_create_reference
* [ ] napi_create_string_latin1
* [ ] napi_create_string_utf16
* [ ] napi_create_string_utf8
* [ ] napi_create_symbol
* [ ] napi_create_typedarray
* [ ] napi_create_type_error
* [ ] napi_create_uint32
* [ ] napi_define_class
* [ ] napi_define_properties
* [ ] napi_delete_element
* [ ] napi_delete_property
* [ ] napi_delete_reference
* [ ] napi_escape_handle
* [ ] napi_get_and_clear_last_exception
* [ ] napi_get_arraybuffer_info
* [ ] napi_get_array_length
* [ ] napi_get_boolean
* [ ] napi_get_cb_info
* [ ] napi_get_dataview_info
* [ ] napi_get_element
* [ ] napi_get_global
* [ ] napi_get_last_error_info
* [ ] napi_get_named_property
* [ ] napi_get_new_target
* [ ] napi_get_null
* [ ] napi_get_property
* [ ] napi_get_property_names
* [ ] napi_get_prototype
* [ ] napi_get_reference_value
* [ ] napi_get_typedarray_info
* [ ] napi_get_undefined
* [ ] napi_get_value_bigint_int64
* [ ] napi_get_value_bigint_uint64
* [ ] napi_get_value_bigint_words
* [ ] napi_get_value_bool
* [ ] napi_get_value_double
* [ ] napi_get_value_external
* [ ] napi_get_value_int32
* [ ] napi_get_value_int64
* [ ] napi_get_value_string_latin1
* [ ] napi_get_value_string_utf16
* [ ] napi_get_value_string_utf8
* [ ] napi_get_value_uint32
* [ ] napi_get_version
* [ ] napi_has_element
* [ ] napi_has_named_property
* [ ] napi_has_own_property
* [ ] napi_has_property
* [ ] napi_instanceof
* [ ] napi_is_array
* [ ] napi_is_arraybuffer
* [ ] napi_is_dataview
* [ ] napi_is_error
* [ ] napi_is_exception_pending
* [ ] napi_is_promise
* [ ] napi_is_typedarray
* [ ] napi_new_instance
* [ ] napi_open_escapable_handle_scope
* [ ] napi_open_handle_scope
* [ ] napi_reference_ref
* [ ] napi_reference_unref
* [ ] napi_reject_deferred
* [ ] napi_remove_wrap
* [ ] napi_resolve_deferred
* [ ] napi_run_script
* [ ] napi_set_element
* [ ] napi_set_named_property
* [ ] napi_set_property
* [ ] napi_strict_equals
* [ ] napi_throw
* [ ] napi_throw_error
* [ ] napi_throw_range_error
* [ ] napi_throw_type_error
* [ ] napi_typeof
* [ ] napi_unwrap
* [ ] napi_wrap

PR-URL: https://github.com/nodejs/node/pull/23786
Reviewed-By: Yazhong Liu 
Reviewed-By: Michael Dawson

src: bundle persistent-to-local methods as class

2018-11-13T04:27:40+00:00

Create a class `PersistentToLocal` which contains three methods,
`Strong`, `Weak`, and `Default`:

* `Strong` returns a `Local` from a strong persistent reference,
* `Weak` returns a `Local` from a weak persistent reference, and
* `Default` decides based on `IsWeak()` which of the above two to call.

These replace `node::StrongPersistentToLocal()`,
`node::WeakPersistentToLocal()`, and `node::PersistentToLocal()`,
respectively.

PR-URL: https://github.com/nodejs/node/pull/24276
Reviewed-By: Joyee Cheung 
Reviewed-By: Colin Ihrig 
Reviewed-By: Anna Henningsen 
Reviewed-By: James M Snell 
Reviewed-By: Refael Ackermann

src: move error handling code into node_errors.cc

2018-11-06T12:58:40+00:00

Move the following code into a new node_errors.cc file and
declare them in node_errors.h for clarity and make it possible
to include them with node_errors.h.

- AppendExceptionLine()
- DecorateErrorStack()
- FatalError()
- OnFatalError()
- PrintErrorString()
- FatalException()
- ReportException()
- FatalTryCatch

And move the following definitions (declared elsewhere than
node_errors.h) to node_errors.cc:

- Abort() (in util.h)
- Assert() (in util.h)

PR-URL: https://github.com/nodejs/node/pull/24058
Reviewed-By: Refael Ackermann 
Reviewed-By: Daniel Bevenius

n-api: add missing handle scopes

2018-11-04T02:27:18+00:00

Currently when building with --debug
test/addons-napi/test_threadsafe_function will error:

$  out/Debug/node test/addons-napi/test_threadsafe_function/test.js
FATAL ERROR: v8::HandleScope::CreateHandle()
  Cannot create a handle without a HandleScope
 1: 0x10004e287 node::DumpBacktrace(__sFILE*) [node/out/Debug/node]
 2: 0x1000cd37b node::Abort() [/node/out/Debug/node]
 3: 0x1000cd69f node::OnFatalError(char const*, char const*)
    [/node/out/Debug/node]
 4: 0x1004df0b1 v8::Utils::ReportApiFailure(char const*, char const*)
    [/nodejs/node/out/Debug/node]
 5: 0x100a8c0a9 v8::internal::HandleScope::Extend(
        v8::internal::Isolate*)
    [/node/out/Debug/node]
 6: 0x1004e4229 v8::EmbedderDataFor(v8::Context*,
                                    int, bool,
                                    char const*)
    [/node/out/Debug/node]
 7: 0x1004e43fa v8::Context::SlowGetAlignedPointerFromEmbedderData(int)
    [/node/out/Debug/node]
 8: 0x10001c26b v8::Context::GetAlignedPointerFromEmbedderData(int)
    [/node/out/Debug/node]
 9: 0x1000144ea node::Environment::GetCurrent(v8::Local)
    [/node/out/Debug/node]
10: 0x1000f49e2 napi_env__::node_env() const
    [/node/out/Debug/node]
11: 0x1000f9885
    (anonymous namespace)::v8impl::ThreadSafeFunction::
        CloseHandlesAndMaybeDelete(bool)
    [/node/out/Debug/node]
12: 0x1000fb34f (anonymous namespace)::v8impl::ThreadSafeFunction::
        DispatchOne()
    [/node/out/Debug/node]
13: 0x1000fb129
    (anonymous namespace)::v8impl::ThreadSafeFunction::
        IdleCb(uv_idle_s*)
    [/node/out/Debug/node]
14: 0x1011a1b69 uv__run_idle
    [/node/out/Debug/node]
15: 0x101198179 uv_run
    [/node/out/Debug/node]
16: 0x1000dfca1
    node::Start(...)
    [/node/out/Debug/node]
17: 0x1000dae50 node::Start(...)
    [/node/out/Debug/node]
18: 0x1000da56f node::Start(int, char**)
    [/node/out/Debug/node]
19: 0x10141112e main
    [/node/out/Debug/node]
20: 0x100001034 start
    [/node/out/Debug/node]
Abort trap: 6

This commit adds two HandleScope's, one to CloseHandlesAndMaybeDelete
and one to the lambda.

SlowGetAlignedPointerFromEmbedderData will only be called for debug
builds:
https://github.com/v8/v8/blob/2ef0aa662fe907a1b36ac1abe7d77ad2bcd27733
/include/v8.h#L10440-L10447

PR-URL: https://github.com/nodejs/node/pull/24011
Reviewed-By: James M Snell 
Reviewed-By: Michael Dawson

n-api: make per-`Context`-ness of `napi_env` explicit

2018-10-24T17:59:38+00:00

Because instances of `napi_env` are created on a per-global-object
basis and because since most N-API functions refer to builtin JS
objects, `napi_env` is essentially in 1:1 correspondence with
`v8::Context`.

This was not clear from the implementation by itself, but has
emerged from conversations with the N-API team.

This patch changes the `napi_env` implementation to:

- Actually store the `v8::Context` it represents.
- Provide more direct access to the `node::Environment`
  to which the `Context` belongs.
- Do not store the `uv_loop_t*` explicitly, since it can be
  inferred from the `node::Environment` and we actually
  have an N-API method for that.
- Replace calls to `isolate->GetCurrentContext()` with
  the more appropriate `napi_env` `Context`.
- Implement a better (although not perfect) way of cleaning
  up `napi_env` instances.

PR-URL: https://github.com/nodejs/node/pull/23689
Reviewed-By: James M Snell 
Reviewed-By: Gus Caplan 
Reviewed-By: Matheus Marchini 
Reviewed-By: Ben Noordhuis 
Reviewed-By: Michael Dawson

src: replace deprecated uses of FunctionTemplate::GetFunction

2018-09-24T03:44:28+00:00

PR-URL: https://github.com/nodejs/node/pull/22993
Reviewed-By: Michaël Zasso 
Reviewed-By: Colin Ihrig 
Reviewed-By: Ujjwal Sharma 
Reviewed-By: Joyee Cheung 
Reviewed-By: Eugene Ostroukhov 
Reviewed-By: Anna Henningsen 
Reviewed-By: James M Snell

src: refactor `Environment::GetCurrent()` usage

2018-09-17T15:20:27+00:00

Make `Environment::GetCurrent()` return `nullptr` if the current
`Context` is not a Node.js context, and for the relevant usage of
this function, either:

- Switch to the better `GetCurrent(args)` variant
- Turn functions in to no-ops where it makes sense
- Make it a `CHECK`, i.e. an API requirement, where it make sense
- Leave a `TODO` comment for verifying what, if anything, is to be done

PR-URL: https://github.com/nodejs/node/pull/22819
Reviewed-By: Gus Caplan 
Reviewed-By: Gireesh Punathil 
Reviewed-By: Eugene Ostroukhov 
Reviewed-By: Refael Ackermann

n-api: add generic finalizer callback

2018-09-13T02:37:42+00:00

Add `napi_add_finalizer()`, which provides the ability to attach data
to an arbitrary object and be notified when that object is garbage-
collected so as to have an opportunity to delete the data previously
attached.

This differs from `napi_wrap()` in that it does not use up the private
slot on the object, and is therefore neither removable, nor retrievable
after the call to `napi_add_finalizer()`. It is assumed that the data
is accessible by other means, yet it must be tied to the lifetime of
the object. This is the case for data passed to a dynamically created
function which is itself heap-allocated and must therefore be freed
along with the function.

Fixes: https://github.com/nodejs/abi-stable-node/issues/313
PR-URL: https://github.com/nodejs/node/pull/22244
Reviewed-By: James M Snell 
Reviewed-By: Michael Dawson

src: make `FIXED_ONE_BYTE_STRING` an inline fn

2018-09-10T03:30:13+00:00

This prevents accidental usage on non-fixed strings.

PR-URL: https://github.com/nodejs/node/pull/22725
Reviewed-By: Daniel Bevenius 
Reviewed-By: Minwoo Jung 
Reviewed-By: Colin Ihrig 
Reviewed-By: Gus Caplan 
Reviewed-By: James M Snell