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

doc: update napi_async_init documentation

Browse Source 
Fixes: https://github.com/nodejs/node/issues/33153

Change documentation to make async_resource required
as opposed to optional in napi-async_init.

Changes over time mean this parameter is required for
proper operation of async hooks (which are still experimental).
This changes the documentation to document what
callers should do. We are doing this only in the doc
in order to avoid a breaking change in N-API. We could
create a new version of the method for which the
parametrer is enforced as mandatory but we should only
do that once async hooks is no longer experimental. In
that case we could deprecate (but not remove this version
of the method).

Signed-off-by: Michael Dawson <michael_dawson@ca.ibm.com>

PR-URL: https://github.com/nodejs/node/pull/33181
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
This commit is contained in:
Michael Dawson 2020-04-30 18:47:10 -04:00
parent 548439a530
commit 3662b0c2c7
1 changed files with 6 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4672,8 +4672,13 @@ napi_status napi_async_init(napi_env env,
```
* `[in] env`: The environment that the API is invoked under.
* `[in] async_resource`: An optional object associated with the async work
* `[in] async_resource`: Object associated with the async work
that will be passed to possible `async_hooks` [`init` hooks][].
In order to retain ABI compatibility with previous versions,
passing `NULL` for `async_resource` will not result in an error, however,
this will result incorrect operation of async hooks for the
napi_async_context created. Potential issues include
loss of async context when using the AsyncLocalStorage API.
* `[in] async_resource_name`: Identifier for the kind of resource
that is being provided for diagnostic information exposed by the
`async_hooks` API.