Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/node/v8-context.h
$ cat -n /usr/include/node/v8-context.h 1 // Copyright 2021 the V8 project authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef INCLUDE_V8_CONTEXT_H_ 6 #define INCLUDE_V8_CONTEXT_H_ 7 8 #include <stdint.h> 9 10 #include <vector> 11 12 #include "v8-data.h" // NOLINT(build/include_directory) 13 #include "v8-local-handle.h" // NOLINT(build/include_directory) 14 #include "v8-maybe.h" // NOLINT(build/include_directory) 15 #include "v8-snapshot.h" // NOLINT(build/include_directory) 16 #include "v8config.h" // NOLINT(build/include_directory) 17 18 namespace v8 { 19 20 class Function; 21 class MicrotaskQueue; 22 class Object; 23 class ObjectTemplate; 24 class Value; 25 class String; 26 27 /** 28 * A container for extension names. 29 */ 30 class V8_EXPORT ExtensionConfiguration { 31 public: 32 ExtensionConfiguration() : name_count_(0), names_(nullptr) {} 33 ExtensionConfiguration(int name_count, const char* names[]) 34 : name_count_(name_count), names_(names) {} 35 36 const char** begin() const { return &names_[0]; } 37 const char** end() const { return &names_[name_count_]; } 38 39 private: 40 const int name_count_; 41 const char** names_; 42 }; 43 44 /** 45 * A sandboxed execution context with its own set of built-in objects 46 * and functions. 47 */ 48 class V8_EXPORT Context : public Data { 49 public: 50 /** 51 * Returns the global proxy object. 52 * 53 * Global proxy object is a thin wrapper whose prototype points to actual 54 * context's global object with the properties like Object, etc. This is done 55 * that way for security reasons (for more details see 56 * https://wiki.mozilla.org/Gecko:SplitWindow). 57 * 58 * Please note that changes to global proxy object prototype most probably 59 * would break VM---v8 expects only global object as a prototype of global 60 * proxy object. 61 */ 62 Local<Object> Global(); 63 64 /** 65 * Detaches the global object from its context before 66 * the global object can be reused to create a new context. 67 */ 68 void DetachGlobal(); 69 70 /** 71 * Creates a new context and returns a handle to the newly allocated 72 * context. 73 * 74 * \param isolate The isolate in which to create the context. 75 * 76 * \param extensions An optional extension configuration containing 77 * the extensions to be installed in the newly created context. 78 * 79 * \param global_template An optional object template from which the 80 * global object for the newly created context will be created. 81 * 82 * \param global_object An optional global object to be reused for 83 * the newly created context. This global object must have been 84 * created by a previous call to Context::New with the same global 85 * template. The state of the global object will be completely reset 86 * and only object identify will remain. 87 * 88 * \param internal_fields_deserializer An optional callback used 89 * to deserialize fields set by 90 * v8::Object::SetAlignedPointerInInternalField() in wrapper objects 91 * from the default context snapshot. It should match the 92 * SerializeInternalFieldsCallback() used by 93 * v8::SnapshotCreator::SetDefaultContext() when the default context 94 * snapshot is created. It does not need to be configured if the default 95 * context snapshot contains no wrapper objects with pointer internal 96 * fields, or if no custom startup snapshot is configured 97 * in the v8::CreateParams used to create the isolate. 98 * 99 * \param microtask_queue An optional microtask queue used to manage 100 * the microtasks created in this context. If not set the per-isolate 101 * default microtask queue would be used. 102 * 103 * \param context_data_deserializer An optional callback used 104 * to deserialize embedder data set by 105 * v8::Context::SetAlignedPointerInEmbedderData() in the default 106 * context from the default context snapshot. It does not need to be 107 * configured if the default context snapshot contains no pointer embedder 108 * data, or if no custom startup snapshot is configured in the 109 * v8::CreateParams used to create the isolate. 110 */ 111 static Local<Context> New( 112 Isolate* isolate, ExtensionConfiguration* extensions = nullptr, 113 MaybeLocal<ObjectTemplate> global_template = MaybeLocal<ObjectTemplate>(), 114 MaybeLocal<Value> global_object = MaybeLocal<Value>(), 115 DeserializeInternalFieldsCallback internal_fields_deserializer = 116 DeserializeInternalFieldsCallback(), 117 MicrotaskQueue* microtask_queue = nullptr, 118 DeserializeContextDataCallback context_data_deserializer = 119 DeserializeContextDataCallback()); 120 121 /** 122 * Create a new context from a (non-default) context snapshot. There 123 * is no way to provide a global object template since we do not create 124 * a new global object from template, but we can reuse a global object. 125 * 126 * \param isolate See v8::Context::New. 127 * 128 * \param context_snapshot_index The index of the context snapshot to 129 * deserialize from. Use v8::Context::New for the default snapshot. 130 * 131 * \param internal_fields_deserializer An optional callback used 132 * to deserialize fields set by 133 * v8::Object::SetAlignedPointerInInternalField() in wrapper objects 134 * from the default context snapshot. It does not need to be 135 * configured if there are no wrapper objects with no internal 136 * pointer fields in the default context snapshot or if no startup 137 * snapshot is configured when the isolate is created. 138 * 139 * \param extensions See v8::Context::New. 140 * 141 * \param global_object See v8::Context::New. 142 * 143 * \param internal_fields_deserializer Similar to 144 * internal_fields_deserializer in v8::Context::New but applies to 145 * the context specified by the context_snapshot_index. 146 * 147 * \param microtask_queue See v8::Context::New. 148 * 149 * \param context_data_deserializer Similar to 150 * context_data_deserializer in v8::Context::New but applies to 151 * the context specified by the context_snapshot_index. 152 */ 153 static MaybeLocal<Context> FromSnapshot( 154 Isolate* isolate, size_t context_snapshot_index, 155 DeserializeInternalFieldsCallback internal_fields_deserializer = 156 DeserializeInternalFieldsCallback(), 157 ExtensionConfiguration* extensions = nullptr, 158 MaybeLocal<Value> global_object = MaybeLocal<Value>(), 159 MicrotaskQueue* microtask_queue = nullptr, 160 DeserializeContextDataCallback context_data_deserializer = 161 DeserializeContextDataCallback()); 162 163 /** 164 * Returns an global object that isn't backed by an actual context. 165 * 166 * The global template needs to have access checks with handlers installed. 167 * If an existing global object is passed in, the global object is detached 168 * from its context. 169 * 170 * Note that this is different from a detached context where all accesses to 171 * the global proxy will fail. Instead, the access check handlers are invoked. 172 * 173 * It is also not possible to detach an object returned by this method. 174 * Instead, the access check handlers need to return nothing to achieve the 175 * same effect. 176 * 177 * It is possible, however, to create a new context from the global object 178 * returned by this method. 179 */ 180 static MaybeLocal<Object> NewRemoteContext( 181 Isolate* isolate, Local<ObjectTemplate> global_template, 182 MaybeLocal<Value> global_object = MaybeLocal<Value>()); 183 184 /** 185 * Sets the security token for the context. To access an object in 186 * another context, the security tokens must match. 187 */ 188 void SetSecurityToken(Local<Value> token); 189 190 /** Restores the security token to the default value. */ 191 void UseDefaultSecurityToken(); 192 193 /** Returns the security token of this context.*/ 194 Local<Value> GetSecurityToken(); 195 196 /** 197 * Enter this context. After entering a context, all code compiled 198 * and run is compiled and run in this context. If another context 199 * is already entered, this old context is saved so it can be 200 * restored when the new context is exited. 201 */ 202 void Enter(); 203 204 /** 205 * Exit this context. Exiting the current context restores the 206 * context that was in place when entering the current context. 207 */ 208 void Exit(); 209 210 /** 211 * Delegate to help with Deep freezing embedder-specific objects (such as 212 * JSApiObjects) that can not be frozen natively. 213 */ 214 class DeepFreezeDelegate { 215 public: 216 /** 217 * Performs embedder-specific operations to freeze the provided embedder 218 * object. The provided object *will* be frozen by DeepFreeze after this 219 * function returns, so only embedder-specific objects need to be frozen. 220 * This function *may not* create new JS objects or perform JS allocations. 221 * Any v8 objects reachable from the provided embedder object that should 222 * also be considered for freezing should be added to the children_out 223 * parameter. Returns true if the operation completed successfully. 224 */ 225 virtual bool FreezeEmbedderObjectAndGetChildren( 226 Local<Object> obj, LocalVector<Object>& children_out) = 0; 227 }; 228 229 /** 230 * Attempts to recursively freeze all objects reachable from this context. 231 * Some objects (generators, iterators, non-const closures) can not be frozen 232 * and will cause this method to throw an error. An optional delegate can be 233 * provided to help freeze embedder-specific objects. 234 * 235 * Freezing occurs in two steps: 236 * 1. "Marking" where we iterate through all objects reachable by this 237 * context, accumulating a list of objects that need to be frozen and 238 * looking for objects that can't be frozen. This step is separated because 239 * it is more efficient when we can assume there is no garbage collection. 240 * 2. "Freezing" where we go through the list of objects and freezing them. 241 * This effectively requires copying them so it may trigger garbage 242 * collection. 243 */ 244 Maybe<void> DeepFreeze(DeepFreezeDelegate* delegate = nullptr); 245 246 /** Returns the isolate associated with a current context. */ 247 Isolate* GetIsolate(); 248 249 /** Returns the microtask queue associated with a current context. */ 250 MicrotaskQueue* GetMicrotaskQueue(); 251 252 /** Sets the microtask queue associated with the current context. */ 253 void SetMicrotaskQueue(MicrotaskQueue* queue); 254 255 /** 256 * The field at kDebugIdIndex used to be reserved for the inspector. 257 * It now serves no purpose. 258 */ 259 enum EmbedderDataFields { kDebugIdIndex = 0 }; 260 261 /** 262 * Return the number of fields allocated for embedder data. 263 */ 264 uint32_t GetNumberOfEmbedderDataFields(); 265 266 /** 267 * Gets the embedder data with the given index, which must have been set by a 268 * previous call to SetEmbedderData with the same index. 269 */ 270 V8_INLINE Local<Value> GetEmbedderData(int index); 271 272 /** 273 * Gets the binding object used by V8 extras. Extra natives get a reference 274 * to this object and can use it to "export" functionality by adding 275 * properties. Extra natives can also "import" functionality by accessing 276 * properties added by the embedder using the V8 API. 277 */ 278 Local<Object> GetExtrasBindingObject(); 279 280 /** 281 * Sets the embedder data with the given index, growing the data as 282 * needed. Note that index 0 currently has a special meaning for Chrome's 283 * debugger. 284 */ 285 void SetEmbedderData(int index, Local<Value> value); 286 287 /** 288 * Gets a 2-byte-aligned native pointer from the embedder data with the given 289 * index, which must have been set by a previous call to 290 * SetAlignedPointerInEmbedderData with the same index. Note that index 0 291 * currently has a special meaning for Chrome's debugger. 292 */ 293 V8_INLINE void* GetAlignedPointerFromEmbedderData(int index); 294 295 /** 296 * Sets a 2-byte-aligned native pointer in the embedder data with the given 297 * index, growing the data as needed. Note that index 0 currently has a 298 * special meaning for Chrome's debugger. 299 */ 300 void SetAlignedPointerInEmbedderData(int index, void* value); 301 302 /** 303 * Control whether code generation from strings is allowed. Calling 304 * this method with false will disable 'eval' and the 'Function' 305 * constructor for code running in this context. If 'eval' or the 306 * 'Function' constructor are used an exception will be thrown. 307 * 308 * If code generation from strings is not allowed the 309 * V8::AllowCodeGenerationFromStrings callback will be invoked if 310 * set before blocking the call to 'eval' or the 'Function' 311 * constructor. If that callback returns true, the call will be 312 * allowed, otherwise an exception will be thrown. If no callback is 313 * set an exception will be thrown. 314 */ 315 void AllowCodeGenerationFromStrings(bool allow); 316 317 /** 318 * Returns true if code generation from strings is allowed for the context. 319 * For more details see AllowCodeGenerationFromStrings(bool) documentation. 320 */ 321 bool IsCodeGenerationFromStringsAllowed() const; 322 323 /** 324 * Sets the error description for the exception that is thrown when 325 * code generation from strings is not allowed and 'eval' or the 'Function' 326 * constructor are called. 327 */ 328 void SetErrorMessageForCodeGenerationFromStrings(Local<String> message); 329 330 /** 331 * Sets the error description for the exception that is thrown when 332 * wasm code generation is not allowed. 333 */ 334 void SetErrorMessageForWasmCodeGeneration(Local<String> message); 335 336 /** 337 * Return data that was previously attached to the context snapshot via 338 * SnapshotCreator, and removes the reference to it. 339 * Repeated call with the same index returns an empty MaybeLocal. 340 */ 341 template <class T> 342 V8_INLINE MaybeLocal<T> GetDataFromSnapshotOnce(size_t index); 343 344 /** 345 * If callback is set, abort any attempt to execute JavaScript in this 346 * context, call the specified callback, and throw an exception. 347 * To unset abort, pass nullptr as callback. 348 */ 349 using AbortScriptExecutionCallback = void (*)(Isolate* isolate, 350 Local<Context> context); 351 void SetAbortScriptExecution(AbortScriptExecutionCallback callback); 352 353 /** 354 * Set or clear hooks to be invoked for promise lifecycle operations. 355 * To clear a hook, set it to an empty v8::Function. Each function will 356 * receive the observed promise as the first argument. If a chaining 357 * operation is used on a promise, the init will additionally receive 358 * the parent promise as the second argument. 359 */ 360 void SetPromiseHooks(Local<Function> init_hook, Local<Function> before_hook, 361 Local<Function> after_hook, 362 Local<Function> resolve_hook); 363 364 bool HasTemplateLiteralObject(Local<Value> object); 365 /** 366 * Stack-allocated class which sets the execution context for all 367 * operations executed within a local scope. 368 */ 369 class V8_NODISCARD Scope { 370 public: 371 explicit V8_INLINE Scope(Local<Context> context) : context_(context) { 372 context_->Enter(); 373 } 374 V8_INLINE ~Scope() { context_->Exit(); } 375 376 private: 377 Local<Context> context_; 378 }; 379 380 /** 381 * Stack-allocated class to support the backup incumbent settings object 382 * stack. 383 * https://html.spec.whatwg.org/multipage/webappapis.html#backup-incumbent-settings-object-stack 384 */ 385 class V8_EXPORT V8_NODISCARD BackupIncumbentScope final { 386 public: 387 /** 388 * |backup_incumbent_context| is pushed onto the backup incumbent settings 389 * object stack. 390 */ 391 explicit BackupIncumbentScope(Local<Context> backup_incumbent_context); 392 ~BackupIncumbentScope(); 393 394 private: 395 friend class internal::Isolate; 396 397 uintptr_t JSStackComparableAddressPrivate() const { 398 return js_stack_comparable_address_; 399 } 400 401 Local<Context> backup_incumbent_context_; 402 uintptr_t js_stack_comparable_address_ = 0; 403 const BackupIncumbentScope* prev_ = nullptr; 404 }; 405 406 V8_INLINE static Context* Cast(Data* data); 407 408 private: 409 friend class Value; 410 friend class Script; 411 friend class Object; 412 friend class Function; 413 414 static void CheckCast(Data* obj); 415 416 internal::Address* GetDataFromSnapshotOnce(size_t index); 417 Local<Value> SlowGetEmbedderData(int index); 418 void* SlowGetAlignedPointerFromEmbedderData(int index); 419 }; 420 421 // --- Implementation --- 422 423 Local<Value> Context::GetEmbedderData(int index) { 424 #ifndef V8_ENABLE_CHECKS 425 using A = internal::Address; 426 using I = internal::Internals; 427 A ctx = internal::ValueHelper::ValueAsAddress(this); 428 A embedder_data = 429 I::ReadTaggedPointerField(ctx, I::kNativeContextEmbedderDataOffset); 430 int value_offset = 431 I::kEmbedderDataArrayHeaderSize + (I::kEmbedderDataSlotSize * index); 432 A value = I::ReadRawField<A>(embedder_data, value_offset); 433 #ifdef V8_COMPRESS_POINTERS 434 // We read the full pointer value and then decompress it in order to avoid 435 // dealing with potential endiannes issues. 436 value = I::DecompressTaggedField(embedder_data, static_cast<uint32_t>(value)); 437 #endif 438 439 auto isolate = reinterpret_cast<v8::Isolate*>( 440 internal::IsolateFromNeverReadOnlySpaceObject(ctx)); 441 return Local<Value>::New(isolate, value); 442 #else 443 return SlowGetEmbedderData(index); 444 #endif 445 } 446 447 void* Context::GetAlignedPointerFromEmbedderData(int index) { 448 #if !defined(V8_ENABLE_CHECKS) 449 using A = internal::Address; 450 using I = internal::Internals; 451 A ctx = internal::ValueHelper::ValueAsAddress(this); 452 A embedder_data = 453 I::ReadTaggedPointerField(ctx, I::kNativeContextEmbedderDataOffset); 454 int value_offset = I::kEmbedderDataArrayHeaderSize + 455 (I::kEmbedderDataSlotSize * index) + 456 I::kEmbedderDataSlotExternalPointerOffset; 457 Isolate* isolate = I::GetIsolateForSandbox(ctx); 458 return reinterpret_cast<void*>( 459 I::ReadExternalPointerField<internal::kEmbedderDataSlotPayloadTag>( 460 isolate, embedder_data, value_offset)); 461 #else 462 return SlowGetAlignedPointerFromEmbedderData(index); 463 #endif 464 } 465 466 template <class T> 467 MaybeLocal<T> Context::GetDataFromSnapshotOnce(size_t index) { 468 if (auto slot = GetDataFromSnapshotOnce(index); slot) { 469 internal::PerformCastCheck( 470 internal::ValueHelper::SlotAsValue<T, false>(slot)); 471 return Local<T>::FromSlot(slot); 472 } 473 return {}; 474 } 475 476 Context* Context::Cast(v8::Data* data) { 477 #ifdef V8_ENABLE_CHECKS 478 CheckCast(data); 479 #endif 480 return static_cast<Context*>(data); 481 } 482 483 } // namespace v8 484 485 #endif // INCLUDE_V8_CONTEXT_H_
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
