src: document the Node.js context embedder data

PR-URL: https://github.com/nodejs/node/pull/53611
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>

src/node_context_data.h

@@ -47,14 +47,84 @@ namespace node {
 #define NODE_CONTEXT_TAG 39
 #endif
 
+/**
+ * These are indexes used to set Node.js-specific data in the V8 contexts
+ * via v8::Context::SetAlignedPointerInEmbedderData() (for pointers) and
+ * v8::Context::SetEmbedderData() (for v8::Values).
+ *
+ * There are five types of contexts in Node.js:
+ * 1. Default V8 context, with nothing Node.js-specific. This is normally only
+ *    created by the embedders that uses v8::Context APIs directly and is not
+ *    available through the Node.js JS APIs. Its context snapshot in the
+ *    built-in v8 startup snapshot is stored using
+ *    v8::SnapshotCreator::SetDefaultContext() - effectively at index 0.
+ * 2. Default Node.js main context. When Node.js is launched typically there is
+ *    a main thread on which a main node::Environment is created. The
+ *    Environment is associated with its own v8::Isolate (env->isolate()) and a
+ *    main v8::Context (env->context()). The corresponding data structure is
+ *    node::NodeMainInstance and the Environment is created in
+ *    node::NodeMainInstance::Run(). Its context snapshot in the built-in V8
+ *    startup snapshot is stored at node::SnapshotData::kNodeMainContextIndex.
+ * 3. Node.js worker context. When a Worker instance is created via
+ *    new worker_threads.Worker(), it gets its own OS thread, its
+ *    own node::Environment, its own v8::Isolate and its own v8::Context.
+ *    The corresponding data structure is node::Worker and the Environment
+ *    is created in node::Worker::Run().
+ *    Its context snapshot in the built-in V8 startup snapshot is stored at
+ *    node::SnapshotData::kNodeBaseContextIndex.
+ * 4. Contextified vm context: When a contextified context is created via
+ *    vm.createContext() or other related vm APIs, the vm.Context instance
+ *    gets its own v8::Context. It shares the thread, the v8::Isolate and
+ *    the node::Environment with the context where the vm APIs are called.
+ *    The corresponding data structure is node::ContextifyContext and
+ *    the initialization code is in node::ContextifyContext::New().
+ *    Its context snapshot in the built-in V8 startup snapshot is stored at
+ *    node::SnapshotData::kNodeVMContextIndex.
+ * 5. ShadowRealm context: When a JS ShadowRealm is created via new ShadowRealm,
+ *    it gets its own v8::Context. It also shares the thread, the v8::Isolate
+ *    and the node::Environment with the context where the ShadowRealm
+ *    constructor is called.  The corresponding data structure is
+ *    node::ShadowRealm and the initialization code is in
+ *    node::ShadowRealm::New().
+ */
 enum ContextEmbedderIndex {
+  // Pointer to the node::Environment associated with the context. Only set for
+  // context type 2-5. Used by Environment::GetCurrent(context) to retrieve
+  // the node::Environment associated with any Node.js context in the
+  // V8 callbacks.
   kEnvironment = NODE_CONTEXT_EMBEDDER_DATA_INDEX,
+  // A v8::Value which is the sandbox object used to create the contextified vm
+  // context. For example the first argument of vm.createContext().
+  // Only set for context type 4 and used in ContextifyContext methods.
   kSandboxObject = NODE_CONTEXT_SANDBOX_OBJECT_INDEX,
+  // A v8::Value indicating whether the context allows WebAssembly code
+  // generation.
+  // Only set for context type 2-5, and for them the default is v8::True.
+  // For context type 4 it's configurable via options.codeGeneration.wasm in the
+  // vm APIs. Used in the default v8::AllowWasmCodeGenerationCallback.
   kAllowWasmCodeGeneration = NODE_CONTEXT_ALLOW_WASM_CODE_GENERATION_INDEX,
+  // A v8::Value indicating whether the context allows code generation via
+  // eval() or new Function().
+  // Only set for context type 2-5, and for them the default is v8::True.
+  // For context type 4 it's configurable via options.codeGeneration.strings in
+  // the
+  // vm APIs. Used in the default v8::AllowCodeGenerationFromStringsCallback.
   kAllowCodeGenerationFromStrings =
       NODE_CONTEXT_ALLOW_CODE_GENERATION_FROM_STRINGS_INDEX,
+  // Pointer to the node::ContextifyContext associated with vm.Contexts.
+  // Only set for context type 4. Used by ContextifyContext::Get() to get
+  // to the ContextifyContext from the property interceptors.
   kContextifyContext = NODE_CONTEXT_CONTEXTIFY_CONTEXT_INDEX,
+  // Pointer to the node::Realm associated with the context.
+  // Only set for context type 2-3 and 5. For context type 2-3, it points to a
+  // node::PrincipalRealm. For context type 5 it points to a node::ShadowRealm.
+  // Used by Realm::GetCurrent(context) to retrieve the associated node::Realm
+  // with any Node.js context in the V8 callbacks.
   kRealm = NODE_CONTEXT_REALM_INDEX,
+  // Pointer to a constant address which is
+  // node::ContextEmbedderTag::kNodeContextTagPtr.
+  // Only set for context type 2-5. Used by ContextEmbedderTag::IsNodeContext()
+  // to check whether a context is a Node.js context.
   kContextTag = NODE_CONTEXT_TAG,
 };