doc: describe several Environments on one embedder-owned isolate

Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com>

Author: codebytere

doc/api/embedding.md

@@ -93,15 +93,42 @@ 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.
+Several `node::Environment`s can share one `v8::Isolate`, one `uv_loop_t` and
+one thread, for example when Node.js is embedded into a process that already
+runs a JavaScript engine and each of its contexts should get Node.js APIs. In
+that configuration:
+
+* The embedder may create the `v8::Isolate` itself instead of calling
+  `node::NewIsolate()`: allocate it with `v8::Isolate::Allocate()`, register it
+  with the `MultiIsolatePlatform` (if one is used) before
+  `v8::Isolate::Initialize()`, optionally pass its own `v8::CppHeap` in the
+  `v8::Isolate::CreateParams`, and call `node::SetIsolateUpForNode()` with the
+  `IsolateSettings` it wants. Node.js uses the isolate's existing `CppHeap`.
+* Each `node::Environment` gets its own main `v8::Context`, which the embedder
+  may create itself and prepare with `node::InitializeContext()`.
+* The `node::Environment`s can share one `node::IsolateData` or use one each;
+  a `node::IsolateData` must outlive every `node::Environment` created from
+  it, and all of them must be freed before the `v8::Isolate` is disposed.
+* At most one `node::Environment` per isolate should register the ESM loader
+  hooks (pass `EnvironmentFlags::kNoRegisterESMLoader` to the others), and
+  `EnvironmentFlags::kNoBrowserGlobals` keeps Node.js from installing timers
+  and other Web globals the host already provides. Every `node::Environment`
+  created without `EnvironmentFlags::kNoCreateInspector` has its own
+  inspector agent; the others throw `ERR_INSPECTOR_NOT_AVAILABLE` from
+  `node:inspector`. Creating `Worker`s requires a `MultiIsolatePlatform` in
+  the `node::IsolateData`.
+* `node::Stop()` terminates JavaScript on the whole isolate unless
+  `StopFlags::kDoNotTerminateIsolate` is passed, so use that flag while other
+  `node::Environment`s on the isolate are still running.
+* `node::FreeEnvironment()` runs the shared loop until the handles of the
+  `node::Environment` being freed have closed. Timers, I/O callbacks and
+  thread pool completions of the other `node::Environment`s that become due
+  in those loop iterations run normally, including their JavaScript; only the
+  `node::Environment` being freed can no longer call into JavaScript.
+* `process.on('beforeExit')` and `process.on('exit')` are per
+  `node::Environment` and only run when the embedder calls
+  `node::EmitProcessBeforeExit()` / `node::EmitProcessExit()` (or
+  `node::SpinEventLoop()`) for that `node::Environment`.
 
 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