1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

n-api: update documentation

Browse Source 
Document which APIs work while an exception is pending. This is the
list of all APIs which do not start with `NAPI_PREAMBLE(env)`.

Fixes: https://github.com/nodejs/abi-stable-node/issues/257
PR-URL: https://github.com/nodejs/node/pull/19078
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
Gabriel Schulhof 2018-03-01 17:44:51 -05:00
parent 9759573997
commit 48b5c11b16
1 changed files with 26 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/api/n-api.md
View File

@ -279,6 +279,8 @@ Do not rely on the content or format of any of the extended information as it
is not subject to SemVer and may change at any time. It is intended only for
logging purposes.
This API can be called even if there is a pending JavaScript exception.
### Exceptions
Any N-API function call may result in a pending JavaScript exception. This is
@ -504,7 +506,6 @@ Returns `napi_ok` if the API succeeded.
This API returns a JavaScript RangeError with the text provided.
#### napi_get_and_clear_last_exception
<!-- YAML
added: v8.0.0
@ -521,6 +522,8 @@ Returns `napi_ok` if the API succeeded.
This API returns true if an exception is pending.
This API can be called even if there is a pending JavaScript exception.
#### napi_is_exception_pending
<!-- YAML
added: v8.0.0
@ -536,6 +539,8 @@ Returns `napi_ok` if the API succeeded.
This API returns true if an exception is pending.
This API can be called even if there is a pending JavaScript exception.
### Fatal Errors
In the event of an unrecoverable error in a native module, a fatal error can be
@ -562,6 +567,8 @@ null-terminated.
The function call does not return, the process will be terminated.
This API can be called even if there is a pending JavaScript exception.
## Object Lifetime management
As N-API calls are made, handles to objects in the heap for the underlying
@ -683,6 +690,8 @@ Returns `napi_ok` if the API succeeded.
This API closes the scope passed in. Scopes must be closed in the
reverse order from which they were created.
This API can be called even if there is a pending JavaScript exception.
#### napi_open_escapable_handle_scope
<!-- YAML
added: v8.0.0
@ -717,6 +726,8 @@ Returns `napi_ok` if the API succeeded.
This API closes the scope passed in. Scopes must be closed in the
reverse order from which they were created.
This API can be called even if there is a pending JavaScript exception.
#### napi_escape_handle
<!-- YAML
added: v8.0.0
@ -740,7 +751,10 @@ This API promotes the handle to the JavaScript object so that it is valid
for the lifetime of the outer scope. It can only be called once per scope.
If it is called more than once an error will be returned.
This API can be called even if there is a pending JavaScript exception.
### References to objects with a lifespan longer than that of the native method
In some cases an addon will need to be able to create and reference objects
with a lifespan longer than that of a single native method invocation. For
example, to create a constructor and later use that constructor
@ -815,6 +829,8 @@ Returns `napi_ok` if the API succeeded.
This API deletes the reference passed in.
This API can be called even if there is a pending JavaScript exception.
#### napi_reference_ref
<!-- YAML
added: v8.0.0
@ -833,7 +849,6 @@ Returns `napi_ok` if the API succeeded.
This API increments the reference count for the reference
passed in and returns the resulting reference count.
#### napi_reference_unref
<!-- YAML
added: v8.0.0
@ -852,7 +867,6 @@ Returns `napi_ok` if the API succeeded.
This API decrements the reference count for the reference
passed in and returns the resulting reference count.
#### napi_get_reference_value
<!-- YAML
added: v8.0.0
@ -1667,8 +1681,6 @@ This API returns various properties of a typed array.
*Warning*: Use caution while using this API since the underlying data buffer
is managed by the VM
#### napi_get_dataview_info
<!-- YAML
added: v8.3.0
@ -1696,7 +1708,6 @@ Returns `napi_ok` if the API succeeded.
This API returns various properties of a DataView.
#### napi_get_value_bool
<!-- YAML
added: v8.0.0
@ -1737,7 +1748,6 @@ in it returns `napi_number_expected`.
This API returns the C double primitive equivalent of the given JavaScript
Number.
#### napi_get_value_external
<!-- YAML
added: v8.0.0
@ -1799,7 +1809,7 @@ Returns `napi_ok` if the API succeeded. If a non-number `napi_value`
is passed in it returns `napi_number_expected`.
This API returns the C int64 primitive equivalent of the given
JavaScript Number
JavaScript Number.
#### napi_get_value_string_latin1
<!-- YAML
@ -2191,8 +2201,6 @@ Returns `napi_ok` if the API succeeded.
This API checks if the Object passsed in is a typed array.
### napi_is_dataview
<!-- YAML
added: v8.3.0
@ -3308,6 +3316,8 @@ Returns `napi_ok` if the API succeeded.
This API frees a previously allocated work object.
This API can be called even if there is a pending JavaScript exception.
### napi_queue_async_work
<!-- YAML
added: v8.0.0
@ -3346,6 +3356,8 @@ the `complete` callback will be invoked with a status value of
`napi_cancelled`. The work should not be deleted before the `complete`
callback invocation, even if it has been successfully cancelled.
This API can be called even if there is a pending JavaScript exception.
## Custom Asynchronous Operations
The simple asynchronous work APIs above may not be appropriate for every
scenario. When using any other asynchronous mechanism, the following APIs
@ -3387,6 +3399,8 @@ napi_status napi_async_destroy(napi_env env,
Returns `napi_ok` if the API succeeded.
This API can be called even if there is a pending JavaScript exception.
### napi_make_callback
<!-- YAML
added: v8.0.0
@ -3469,6 +3483,8 @@ NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
- `[in] env`: The environment that the API is invoked under.
- `[in] scope`: The scope to be closed.
This API can be called even if there is a pending JavaScript exception.
## Version Management
### napi_get_node_version