doc: clarify async execute callback usage

Clarify that calls to N-API should be avoided in
the 'execute' callback.

PR-URL: https://github.com/nodejs/node/pull/21217
Refs: https://github.com/nodejs/help/issues/1318
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

1 files changed, 13 insertions, 1 deletions

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index bc4d3e07c3..ef2396409b 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -179,6 +179,11 @@ operations. Callback functions must statisfy the following signature:
 typedef void (*napi_async_execute_callback)(napi_env env, void* data);
 ```
 
+Implementations of this type of function should avoid making any N-API calls
+that could result in the execution of JavaScript or interaction with
+JavaScript objects. Most often, any code that needs to make N-API
+calls should be made in `napi_async_complete_callback` instead.
+
 #### napi_async_complete_callback
 Function pointer used with functions that support asynchronous
 operations. Callback functions must statisfy the following signature:
@@ -3322,7 +3327,14 @@ asynchronous workers. Instances are created/deleted with
 
 The `execute` and `complete` callbacks are functions that will be
 invoked when the executor is ready to execute and when it completes its
-task respectively. These functions implement the following interfaces:
+task respectively.
+
+The `execute` function should avoid making any N-API calls
+that could result in the execution of JavaScript or interaction with
+JavaScript objects. Most often, any code that needs to make N-API
+calls should be made in `complete` callback instead.
+
+These functions implement the following interfaces:
 
 ```C
 typedef void (*napi_async_execute_callback)(napi_env env,