Skip to content

Commit

Permalink
n-api: update documentation
Browse files Browse the repository at this point in the history
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: nodejs/abi-stable-node#257
PR-URL: #19078
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
Gabriel Schulhof authored and MylesBorins committed Mar 20, 2018
1 parent 5b12d3a commit 12f19a6
Showing 1 changed file with 26 additions and 10 deletions.
36 changes: 26 additions & 10 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,8 @@ valid up until an n-api function is called on the same `env`.
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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -682,6 +689,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
Expand Down Expand Up @@ -716,6 +725,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
Expand All @@ -739,7 +750,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
Expand Down Expand Up @@ -814,6 +828,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
Expand All @@ -832,7 +848,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
Expand All @@ -851,7 +866,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
Expand Down Expand Up @@ -1665,8 +1679,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
Expand Down Expand Up @@ -1694,7 +1706,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
Expand Down Expand Up @@ -1735,7 +1746,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
Expand Down Expand Up @@ -1797,7 +1807,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
Expand Down Expand Up @@ -2189,8 +2199,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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 12f19a6

Please sign in to comment.