src: document the Node.js context embedder data · nodejs/node@e6d735a

#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,

};