Commit df0f7a3
doc: clarify async execute callback usage
Clarify that calls to N-API should be avoided in
the 'execute' callback.
PR-URL: #21217
Refs: nodejs/help#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 parent 521f8f1 commit df0f7a3
1 file changed
Lines changed: 13 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -179,6 +179,11 @@ operations. Callback functions must statisfy the following signature: | |||
| 179 | 179 | typedef void (*napi_async_execute_callback)(napi_env env, void* data); | |
| 180 | 180 | ``` | |
| 181 | 181 | ||
| 182 | + Implementations of this type of function should avoid making any N-API calls | ||
| 183 | + that could result in the execution of JavaScript or interaction with | ||
| 184 | + JavaScript objects. Most often, any code that needs to make N-API | ||
| 185 | + calls should be made in `napi_async_complete_callback` instead. | ||
| 186 | + | ||
| 182 | 187 | #### napi_async_complete_callback | |
| 183 | 188 | Function pointer used with functions that support asynchronous | |
| 184 | 189 | operations. Callback functions must statisfy the following signature: | |
@@ -3322,7 +3327,14 @@ asynchronous workers. Instances are created/deleted with | |||
| 3322 | 3327 | ||
| 3323 | 3328 | The `execute` and `complete` callbacks are functions that will be | |
| 3324 | 3329 | invoked when the executor is ready to execute and when it completes its | |
| 3325 | - task respectively. These functions implement the following interfaces: | ||
| 3330 | + task respectively. | ||
| 3331 | + | ||
| 3332 | + The `execute` function should avoid making any N-API calls | ||
| 3333 | + that could result in the execution of JavaScript or interaction with | ||
| 3334 | + JavaScript objects. Most often, any code that needs to make N-API | ||
| 3335 | + calls should be made in `complete` callback instead. | ||
| 3336 | + | ||
| 3337 | + These functions implement the following interfaces: | ||
| 3326 | 3338 | ||
| 3327 | 3339 | ```C | |
| 3328 | 3340 | typedef void (*napi_async_execute_callback)(napi_env env, | |
0 commit comments