From e11e8fd2e61c381d2c8b0dc8b41527ce85ad4136 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 8 Jun 2018 14:08:44 -0400 Subject: [PATCH 1/2] doc: clarify async execute callback usage Clarify that calls to N-API should be avoided in the 'execute' callback. Refs: https://github.com/nodejs/help/issues/1318 --- doc/api/n-api.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index bc4d3e07c34125..f45a17c97c1710 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, From 158c729990ac66fb53980c3efd379c000d2624e3 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 13 Jun 2018 17:00:28 -0400 Subject: [PATCH 2/2] squash: address comments. --- doc/api/n-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index f45a17c97c1710..ef2396409b45a3 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -181,7 +181,7 @@ 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 +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 @@ -3331,7 +3331,7 @@ 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 +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: