From ab63ce55583e5ede79dca151ecdb0cef23dea935 Mon Sep 17 00:00:00 2001 From: Eric Bickle Date: Thu, 1 Mar 2018 09:27:16 -0800 Subject: [PATCH 1/3] doc: fix n-api asynchronous threading documentation Documentation for N-API Custom Asynchronous Operations incorrectly stated that async execution happens on the main event loop. Added details to napi_create_async_work about which threads are used to invoke the execute and complete callbacks. Fixes: #19071 --- doc/api/n-api.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index ff470acfe1682d..27248933540500 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3269,9 +3269,11 @@ napi_status napi_create_async_work(napi_env env, - `[in] async_resource_name`: Identifier for the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. - `[in] execute`: The native function which should be called to excute -the logic asynchronously. +the logic asynchronously. The given function is called from a worker pool +thread and executes in parallel with the main event loop thread. - `[in] complete`: The native function which will be called when the -asynchronous logic is comple or is cancelled. +asynchronous logic is comple or is cancelled. The given function is called +from the main event loop thread. - `[in] data`: User-provided data context. This will be passed back into the execute and complete functions. - `[out] result`: `napi_async_work*` which is the handle to the newly created @@ -3346,8 +3348,7 @@ callback invocation, even if it has been successfully cancelled. ## Custom Asynchronous Operations The simple asynchronous work APIs above may not be appropriate for every -scenario, because with those the async execution still happens on the main -event loop. When using any other async mechanism, the following APIs are +scenario. When using any other async mechanism, the following APIs are necessary to ensure an async operation is properly tracked by the runtime. ### napi_async_init From f59ea55f14f4f80b16ffca6204a054a70a63c482 Mon Sep 17 00:00:00 2001 From: Eric Bickle Date: Thu, 1 Mar 2018 10:41:26 -0800 Subject: [PATCH 2/3] doc: fix typo in napi_create_async_work documentation Documentation for napi_create_async_work was missing part of the word "completed" in the parameter documentation --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 27248933540500..1c9d7a3b076d4c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3272,7 +3272,7 @@ being provided for diagnostic information exposed by the `async_hooks` API. the logic asynchronously. The given function is called from a worker pool thread and executes in parallel with the main event loop thread. - `[in] complete`: The native function which will be called when the -asynchronous logic is comple or is cancelled. The given function is called +asynchronous logic is completed or is cancelled. The given function is called from the main event loop thread. - `[in] data`: User-provided data context. This will be passed back into the execute and complete functions. From 3493aa9b611be03d8f0450be2a6bad3c04c2a58e Mon Sep 17 00:00:00 2001 From: Eric Bickle Date: Thu, 1 Mar 2018 16:55:55 -0800 Subject: [PATCH 3/3] doc: remove async abbreviation and clarify threading behavior Changed 'async' to 'asynchronous' in the documentation for Custom Asynchronous Operations. Changed "executes in parallel" to "can execute in parallel" for the documentation of napi_create_async_work execute parameter. --- doc/api/n-api.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 1c9d7a3b076d4c..57547fc36d8f5c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3270,7 +3270,7 @@ napi_status napi_create_async_work(napi_env env, being provided for diagnostic information exposed by the `async_hooks` API. - `[in] execute`: The native function which should be called to excute the logic asynchronously. The given function is called from a worker pool -thread and executes in parallel with the main event loop thread. +thread and can execute in parallel with the main event loop thread. - `[in] complete`: The native function which will be called when the asynchronous logic is completed or is cancelled. The given function is called from the main event loop thread. @@ -3348,8 +3348,9 @@ callback invocation, even if it has been successfully cancelled. ## Custom Asynchronous Operations The simple asynchronous work APIs above may not be appropriate for every -scenario. When using any other async mechanism, the following APIs are -necessary to ensure an async operation is properly tracked by the runtime. +scenario. When using any other asynchronous mechanism, the following APIs +are necessary to ensure an asynchronous operation is properly tracked by +the runtime. ### napi_async_init