doc,src: clarify that one napi_env is per-module

PR-URL: #31102
Reviewed-By: Gabriel Schulhof <[email protected]>
Reviewed-By: Jiawen Geng <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>

Author: legendecas

doc/api/n-api.md

@@ -493,8 +493,12 @@ implementation can use to persist VM-specific state. This structure is passed
 to native functions when they're invoked, and it must be passed back when
 making N-API calls. Specifically, the same `napi_env` that was passed in when
 the initial native function was called must be passed to any subsequent
-nested N-API calls. Caching the `napi_env` for the purpose of general reuse is
-not allowed.
+nested N-API calls. Caching the `napi_env` for the purpose of general reuse,
+and passing the `napi_env` between instances of the same addon running on
+different [`Worker`][] threads is not allowed. The `napi_env` becomes invalid
+when an instance of a native addon is unloaded. Notification of this event is
+delivered through the callbacks given to [`napi_add_env_cleanup_hook`][] and
+[`napi_set_instance_data`][].
 
 ### napi_value
 
@@ -5304,8 +5308,10 @@ This API may only be called from the main thread.
 [Xcode]: https://developer.apple.com/xcode/
 [`Number.MAX_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.max_safe_integer
 [`Number.MIN_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.min_safe_integer
+[`Worker`]: worker_threads.html#worker_threads_class_worker
 [`global`]: globals.html#globals_global
 [`init` hooks]: async_hooks.html#async_hooks_init_asyncid_type_triggerasyncid_resource
+[`napi_add_env_cleanup_hook`]: #n_api_napi_add_env_cleanup_hook
 [`napi_add_finalizer`]: #n_api_napi_add_finalizer
 [`napi_async_init`]: #n_api_napi_async_init
 [`napi_cancel_async_work`]: #n_api_napi_cancel_async_work
@@ -5341,6 +5347,7 @@ This API may only be called from the main thread.
 [`napi_queue_async_work`]: #n_api_napi_queue_async_work
 [`napi_reference_ref`]: #n_api_napi_reference_ref
 [`napi_reference_unref`]: #n_api_napi_reference_unref
+[`napi_set_instance_data`]: #n_api_napi_set_instance_data
 [`napi_set_property`]: #n_api_napi_set_property
 [`napi_throw_error`]: #n_api_napi_throw_error
 [`napi_throw_range_error`]: #n_api_napi_throw_range_error

src/node_api.cc

@@ -471,8 +471,7 @@ void napi_module_register_by_symbol(v8::Local<v8::Object> exports,
     return;
   }
 
-  // Create a new napi_env for this module or reference one if a pre-existing
-  // one is found.
+  // Create a new napi_env for this specific module.
   napi_env env = v8impl::NewEnv(context);
 
   napi_value _exports;