Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

n-api: update documentation #19078

Closed
wants to merge 1 commit into from
Closed

n-api: update documentation #19078

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 26 additions & 10 deletions doc/api/n-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
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 @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
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