Skip to content

Commit

Permalink
src: document the Node.js context embedder data
Browse files Browse the repository at this point in the history
PR-URL: #53611
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
  • Loading branch information
joyeecheung authored and marco-ippolito committed Aug 19, 2024
1 parent 584beaa commit e6d735a
Showing 1 changed file with 70 additions and 0 deletions.
70 changes: 70 additions & 0 deletions src/node_context_data.h
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};

Expand Down

0 comments on commit e6d735a

Please sign in to comment.