From 1abb16883816b3e23da0ec9c8429a79f490e2c9c Mon Sep 17 00:00:00 2001 From: Eric Bickle Date: Thu, 1 Mar 2018 09:27:16 -0800 Subject: [PATCH] doc: fix n-api asynchronous threading docs 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. 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. Backport-PR-URL: https://github.com/nodejs/node/pull/19265 PR-URL: https://github.com/nodejs/node/pull/19073 Fixes: https://github.com/nodejs/node/issues/19071 Reviewed-By: Michael Dawson Reviewed-By: James M Snell Reviewed-By: Ruben Bridgewater --- doc/api/n-api.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index aad4cadd948ad2..9055e44da7b562 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3283,9 +3283,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 can execute 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 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. - `[out] result`: `napi_async_work*` which is the handle to the newly created @@ -3361,9 +3363,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, because with those the async execution still happens on the main -event loop. 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