Skip to content

Commit df63adf

Browse files
Gabriel SchulhofMylesBorins
Gabriel Schulhof
authored andcommitted
n-api: update documentation
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 Backport-PR-URL: #19265 PR-URL: #19078 Reviewed-By: Michael Dawson <[email protected]>
1 parent b26410e commit df63adf

File tree

1 file changed

+26
-10
lines changed

1 file changed

+26
-10
lines changed

doc/api/n-api.md

+26-10
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,8 @@ valid up until an n-api function is called on the same `env`.
279279
information as it is not subject to SemVer and may change at any time.
280280
It is intended only for logging purposes.
281281

282+
This API can be called even if there is a pending JavaScript exception.
283+
282284

283285
### Exceptions
284286
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.
504506

505507
This API returns a JavaScript RangeError with the text provided.
506508

507-
508509
#### napi_get_and_clear_last_exception
509510
<!-- YAML
510511
added: v8.0.0
@@ -521,6 +522,8 @@ Returns `napi_ok` if the API succeeded.
521522

522523
This API returns true if an exception is pending.
523524

525+
This API can be called even if there is a pending JavaScript exception.
526+
524527
#### napi_is_exception_pending
525528
<!-- YAML
526529
added: v8.0.0
@@ -536,6 +539,8 @@ Returns `napi_ok` if the API succeeded.
536539

537540
This API returns true if an exception is pending.
538541

542+
This API can be called even if there is a pending JavaScript exception.
543+
539544
### Fatal Errors
540545

541546
In the event of an unrecoverable error in a native module, a fatal error can be
@@ -562,6 +567,8 @@ null-terminated.
562567

563568
The function call does not return, the process will be terminated.
564569

570+
This API can be called even if there is a pending JavaScript exception.
571+
565572
## Object Lifetime management
566573

567574
As N-API calls are made, handles to objects in the heap for the underlying
@@ -682,6 +689,8 @@ Returns `napi_ok` if the API succeeded.
682689
This API closes the scope passed in. Scopes must be closed in the
683690
reverse order from which they were created.
684691

692+
This API can be called even if there is a pending JavaScript exception.
693+
685694
#### napi_open_escapable_handle_scope
686695
<!-- YAML
687696
added: v8.0.0
@@ -716,6 +725,8 @@ Returns `napi_ok` if the API succeeded.
716725
This API closes the scope passed in. Scopes must be closed in the
717726
reverse order from which they were created.
718727

728+
This API can be called even if there is a pending JavaScript exception.
729+
719730
#### napi_escape_handle
720731
<!-- YAML
721732
added: v8.0.0
@@ -739,7 +750,10 @@ This API promotes the handle to the JavaScript object so that it is valid
739750
for the lifetime of the outer scope. It can only be called once per scope.
740751
If it is called more than once an error will be returned.
741752

753+
This API can be called even if there is a pending JavaScript exception.
754+
742755
### References to objects with a lifespan longer than that of the native method
756+
743757
In some cases an addon will need to be able to create and reference objects
744758
with a lifespan longer than that of a single native method invocation. For
745759
example, to create a constructor and later use that constructor
@@ -814,6 +828,8 @@ Returns `napi_ok` if the API succeeded.
814828

815829
This API deletes the reference passed in.
816830

831+
This API can be called even if there is a pending JavaScript exception.
832+
817833
#### napi_reference_ref
818834
<!-- YAML
819835
added: v8.0.0
@@ -832,7 +848,6 @@ Returns `napi_ok` if the API succeeded.
832848
This API increments the reference count for the reference
833849
passed in and returns the resulting reference count.
834850

835-
836851
#### napi_reference_unref
837852
<!-- YAML
838853
added: v8.0.0
@@ -851,7 +866,6 @@ Returns `napi_ok` if the API succeeded.
851866
This API decrements the reference count for the reference
852867
passed in and returns the resulting reference count.
853868

854-
855869
#### napi_get_reference_value
856870
<!-- YAML
857871
added: v8.0.0
@@ -1678,8 +1692,6 @@ This API returns various properties of a typed array.
16781692
*Warning*: Use caution while using this API since the underlying data buffer
16791693
is managed by the VM
16801694

1681-
1682-
16831695
#### napi_get_dataview_info
16841696
<!-- YAML
16851697
added: v8.3.0
@@ -1707,7 +1719,6 @@ Returns `napi_ok` if the API succeeded.
17071719

17081720
This API returns various properties of a DataView.
17091721

1710-
17111722
#### napi_get_value_bool
17121723
<!-- YAML
17131724
added: v8.0.0
@@ -1748,7 +1759,6 @@ in it returns `napi_number_expected`.
17481759
This API returns the C double primitive equivalent of the given JavaScript
17491760
Number.
17501761

1751-
17521762
#### napi_get_value_external
17531763
<!-- YAML
17541764
added: v8.0.0
@@ -1810,7 +1820,7 @@ Returns `napi_ok` if the API succeeded. If a non-number `napi_value`
18101820
is passed in it returns `napi_number_expected`.
18111821

18121822
This API returns the C int64 primitive equivalent of the given
1813-
JavaScript Number
1823+
JavaScript Number.
18141824

18151825
#### napi_get_value_string_latin1
18161826
<!-- YAML
@@ -2202,8 +2212,6 @@ Returns `napi_ok` if the API succeeded.
22022212

22032213
This API checks if the Object passsed in is a typed array.
22042214

2205-
2206-
22072215
### napi_is_dataview
22082216
<!-- YAML
22092217
added: v8.3.0
@@ -3323,6 +3331,8 @@ Returns `napi_ok` if the API succeeded.
33233331

33243332
This API frees a previously allocated work object.
33253333

3334+
This API can be called even if there is a pending JavaScript exception.
3335+
33263336
### napi_queue_async_work
33273337
<!-- YAML
33283338
added: v8.0.0
@@ -3361,6 +3371,8 @@ the `complete` callback will be invoked with a status value of
33613371
`napi_cancelled`. The work should not be deleted before the `complete`
33623372
callback invocation, even if it has been successfully cancelled.
33633373

3374+
This API can be called even if there is a pending JavaScript exception.
3375+
33643376
## Custom Asynchronous Operations
33653377
The simple asynchronous work APIs above may not be appropriate for every
33663378
scenario. When using any other asynchronous mechanism, the following APIs
@@ -3402,6 +3414,8 @@ napi_status napi_async_destroy(napi_env env,
34023414

34033415
Returns `napi_ok` if the API succeeded.
34043416

3417+
This API can be called even if there is a pending JavaScript exception.
3418+
34053419
### napi_make_callback
34063420
<!-- YAML
34073421
added: v8.0.0
@@ -3484,6 +3498,8 @@ NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
34843498
- `[in] env`: The environment that the API is invoked under.
34853499
- `[in] scope`: The scope to be closed.
34863500

3501+
This API can be called even if there is a pending JavaScript exception.
3502+
34873503
## Version Management
34883504

34893505
### napi_get_node_version

0 commit comments

Comments
 (0)