N-API: Lifetime of napi_env is unclear

[argv-minus-one]

• Version: 11.10.0
• Platform: Linux 5.3.0-1-amd64 deps: update openssl to 1.0.1j #1 SMP Debian 5.3.7-1 (2019-10-19) x86_64 GNU/Linux

The N-API documentation says not to keep napi_env values around. This would seem to imply that napi_env values are valid only for the duration of a single call into native code (the module initializer, a native function call, etc).

However, in the C++ wrapper, the Reference class (which is meant to live longer than a single native call) keeps a long-lived napi_env value around, seemingly violating the documented lifetime!

Please clarify the lifetime of napi_env values in the documentation. Just how long is a napi_env really valid for? A single native call? The entire time until the env_shutdown_hooks are run and the native module is unloaded? Somewhere in between?

[legendecas]

Fixed by #31102. Please reopen freely if needed.