@@ -93,6 +93,16 @@ to as `node::Environment`. Each `node::Environment` is associated with:
   that `node::IsolateData` is shared only among `node::Environment`s that
   use the same `v8::Isolate`, Node.js does not perform this check.
 
+`node::Environment`s that share a `node::IsolateData` also share its
+`uv_loop_t`. `node::FreeEnvironment()` runs that loop until the handles of the
+`node::Environment` being freed have closed, and JavaScript execution is
+disallowed on the whole `v8::Isolate` while it does, so pending timers, I/O
+callbacks and thread pool completions that belong to other `node::Environment`s
+on the same loop can run inside that call without being able to call into
+JavaScript. `node::Environment`s that are freed independently of one another
+should each use their own `uv_loop_t` and `node::IsolateData`, or the embedder
+should make sure the others have no pending work when one of them is freed.
+
 In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs
 to be provided. One possible choice is the default Node.js allocator, which
 can be created through `node::ArrayBufferAllocator::Create()`. Using the Node.js
 
@@ -882,6 +882,9 @@ NODE_EXTERN v8::MaybeLocal<v8::Value> LoadEnvironment(
     const ModuleData* entry_point,
     EmbedderPreloadCallback preload = nullptr);
 
+// Runs `env`'s event loop until its handles have closed, with JavaScript
+// execution disallowed on the isolate; see doc/api/embedding.md if that loop
+// is shared with other Environments.
 NODE_EXTERN void FreeEnvironment(Environment* env);
 
 // Set a callback that is called when process.exit() is called from JS,