From 8825dc321afcee9dc0cc209e5bd54b0397848914 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Sat, 6 Jul 2024 21:12:30 +0200 Subject: [PATCH] src: document the Node.js context embedder data PR-URL: https://github.com/nodejs/node/pull/53611 Reviewed-By: Anna Henningsen Reviewed-By: Chengzhong Wu --- src/node_context_data.h | 70 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/src/node_context_data.h b/src/node_context_data.h index 1854eb879ee..482e8b9fd3a 100644 --- a/src/node_context_data.h +++ b/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, };