From a62c146070c08b3d283f9ba977e144fab742307f Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 30 Apr 2020 18:47:10 -0400 Subject: [PATCH] doc: update napi_async_init documentation 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 --- doc/api/n-api.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 5552aaf57bfcad..ca55d2f6e1d09c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -4672,7 +4672,7 @@ 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] async_resource_name`: Identifier for the kind of resource that is being provided for diagnostic information exposed by the @@ -4681,6 +4681,12 @@ napi_status napi_async_init(napi_env env, Returns `napi_ok` if the API succeeded. +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 include +loss of async context when using the AsyncLocalStorage API. + ### napi_async_destroy