1 // Copyright 2007-2009 the V8 project authors. All rights reserved. 2 // Redistribution and use in source and binary forms, with or without 3 // modification, are permitted provided that the following conditions are 4 // met: 5 // 6 // * Redistributions of source code must retain the above copyright 7 // notice, this list of conditions and the following disclaimer. 8 // * Redistributions in binary form must reproduce the above 9 // copyright notice, this list of conditions and the following 10 // disclaimer in the documentation and/or other materials provided 11 // with the distribution. 12 // * Neither the name of Google Inc. nor the names of its 13 // contributors may be used to endorse or promote products derived 14 // from this software without specific prior written permission. 15 // 16 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 18 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 19 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 20 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 21 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 22 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 26 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 28 /** \mainpage V8 API Reference Guide 29 * 30 * V8 is Google's open source JavaScript engine. 31 * 32 * This set of documents provides reference material generated from the 33 * V8 header file, include/v8.h. 34 * 35 * For other documentation see http://code.google.com/apis/v8/ 36 */ 37 38 #ifndef V8_H_ 39 #define V8_H_ 40 41 #include "v8stdint.h" 42 43 #ifdef _WIN32 44 45 // Setup for Windows DLL export/import. When building the V8 DLL the 46 // BUILDING_V8_SHARED needs to be defined. When building a program which uses 47 // the V8 DLL USING_V8_SHARED needs to be defined. When either building the V8 48 // static library or building a program which uses the V8 static library neither 49 // BUILDING_V8_SHARED nor USING_V8_SHARED should be defined. 50 #if defined(BUILDING_V8_SHARED) && defined(USING_V8_SHARED) 51 #error both BUILDING_V8_SHARED and USING_V8_SHARED are set - please check the\ 52 build configuration to ensure that at most one of these is set 53 #endif 54 55 #ifdef BUILDING_V8_SHARED 56 #define V8EXPORT __declspec(dllexport) 57 #elif USING_V8_SHARED 58 #define V8EXPORT __declspec(dllimport) 59 #else 60 #define V8EXPORT 61 #endif // BUILDING_V8_SHARED 62 63 #else // _WIN32 64 65 // Setup for Linux shared library export. There is no need to distinguish 66 // between building or using the V8 shared library, but we should not 67 // export symbols when we are building a static library. 68 #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(V8_SHARED) 69 #define V8EXPORT __attribute__ ((visibility("default"))) 70 #else // defined(__GNUC__) && (__GNUC__ >= 4) 71 #define V8EXPORT 72 #endif // defined(__GNUC__) && (__GNUC__ >= 4) 73 74 #endif // _WIN32 75 76 /** 77 * The v8 JavaScript engine. 78 */ 79 namespace v8 { 80 81 class Context; 82 class String; 83 class Value; 84 class Utils; 85 class Number; 86 class Object; 87 class Array; 88 class Int32; 89 class Uint32; 90 class External; 91 class Primitive; 92 class Boolean; 93 class Integer; 94 class Function; 95 class Date; 96 class ImplementationUtilities; 97 class Signature; 98 template <class T> class Handle; 99 template <class T> class Local; 100 template <class T> class Persistent; 101 class FunctionTemplate; 102 class ObjectTemplate; 103 class Data; 104 class AccessorInfo; 105 class StackTrace; 106 class StackFrame; 107 108 namespace internal { 109 110 class Arguments; 111 class Object; 112 class Heap; 113 class HeapObject; 114 class Isolate; 115 } 116 117 118 // --- W e a k H a n d l e s 119 120 121 /** 122 * A weak reference callback function. 123 * 124 * This callback should either explicitly invoke Dispose on |object| if 125 * V8 wrapper is not needed anymore, or 'revive' it by invocation of MakeWeak. 126 * 127 * \param object the weak global object to be reclaimed by the garbage collector 128 * \param parameter the value passed in when making the weak global object 129 */ 130 typedef void (*WeakReferenceCallback)(Persistent<Value> object, 131 void* parameter); 132 133 134 // --- H a n d l e s --- 135 136 #define TYPE_CHECK(T, S) \ 137 while (false) { \ 138 *(static_cast<T* volatile*>(0)) = static_cast<S*>(0); \ 139 } 140 141 /** 142 * An object reference managed by the v8 garbage collector. 143 * 144 * All objects returned from v8 have to be tracked by the garbage 145 * collector so that it knows that the objects are still alive. Also, 146 * because the garbage collector may move objects, it is unsafe to 147 * point directly to an object. Instead, all objects are stored in 148 * handles which are known by the garbage collector and updated 149 * whenever an object moves. Handles should always be passed by value 150 * (except in cases like out-parameters) and they should never be 151 * allocated on the heap. 152 * 153 * There are two types of handles: local and persistent handles. 154 * Local handles are light-weight and transient and typically used in 155 * local operations. They are managed by HandleScopes. Persistent 156 * handles can be used when storing objects across several independent 157 * operations and have to be explicitly deallocated when they're no 158 * longer used. 159 * 160 * It is safe to extract the object stored in the handle by 161 * dereferencing the handle (for instance, to extract the Object* from 162 * an Handle<Object>); the value will still be governed by a handle 163 * behind the scenes and the same rules apply to these values as to 164 * their handles. 165 */ 166 template <class T> class Handle { 167 public: 168 169 /** 170 * Creates an empty handle. 171 */ 172 inline Handle(); 173 174 /** 175 * Creates a new handle for the specified value. 176 */ 177 inline explicit Handle(T* val) : val_(val) { } 178 179 /** 180 * Creates a handle for the contents of the specified handle. This 181 * constructor allows you to pass handles as arguments by value and 182 * to assign between handles. However, if you try to assign between 183 * incompatible handles, for instance from a Handle<String> to a 184 * Handle<Number> it will cause a compiletime error. Assigning 185 * between compatible handles, for instance assigning a 186 * Handle<String> to a variable declared as Handle<Value>, is legal 187 * because String is a subclass of Value. 188 */ 189 template <class S> inline Handle(Handle<S> that) 190 : val_(reinterpret_cast<T*>(*that)) { 191 /** 192 * This check fails when trying to convert between incompatible 193 * handles. For example, converting from a Handle<String> to a 194 * Handle<Number>. 195 */ 196 TYPE_CHECK(T, S); 197 } 198 199 /** 200 * Returns true if the handle is empty. 201 */ 202 inline bool IsEmpty() const { return val_ == 0; } 203 204 inline T* operator->() const { return val_; } 205 206 inline T* operator*() const { return val_; } 207 208 /** 209 * Sets the handle to be empty. IsEmpty() will then return true. 210 */ 211 inline void Clear() { this->val_ = 0; } 212 213 /** 214 * Checks whether two handles are the same. 215 * Returns true if both are empty, or if the objects 216 * to which they refer are identical. 217 * The handles' references are not checked. 218 */ 219 template <class S> inline bool operator==(Handle<S> that) const { 220 internal::Object** a = reinterpret_cast<internal::Object**>(**this); 221 internal::Object** b = reinterpret_cast<internal::Object**>(*that); 222 if (a == 0) return b == 0; 223 if (b == 0) return false; 224 return *a == *b; 225 } 226 227 /** 228 * Checks whether two handles are different. 229 * Returns true if only one of the handles is empty, or if 230 * the objects to which they refer are different. 231 * The handles' references are not checked. 232 */ 233 template <class S> inline bool operator!=(Handle<S> that) const { 234 return !operator==(that); 235 } 236 237 template <class S> static inline Handle<T> Cast(Handle<S> that) { 238 #ifdef V8_ENABLE_CHECKS 239 // If we're going to perform the type check then we have to check 240 // that the handle isn't empty before doing the checked cast. 241 if (that.IsEmpty()) return Handle<T>(); 242 #endif 243 return Handle<T>(T::Cast(*that)); 244 } 245 246 template <class S> inline Handle<S> As() { 247 return Handle<S>::Cast(*this); 248 } 249 250 private: 251 T* val_; 252 }; 253 254 255 /** 256 * A light-weight stack-allocated object handle. All operations 257 * that return objects from within v8 return them in local handles. They 258 * are created within HandleScopes, and all local handles allocated within a 259 * handle scope are destroyed when the handle scope is destroyed. Hence it 260 * is not necessary to explicitly deallocate local handles. 261 */ 262 template <class T> class Local : public Handle<T> { 263 public: 264 inline Local(); 265 template <class S> inline Local(Local<S> that) 266 : Handle<T>(reinterpret_cast<T*>(*that)) { 267 /** 268 * This check fails when trying to convert between incompatible 269 * handles. For example, converting from a Handle<String> to a 270 * Handle<Number>. 271 */ 272 TYPE_CHECK(T, S); 273 } 274 template <class S> inline Local(S* that) : Handle<T>(that) { } 275 template <class S> static inline Local<T> Cast(Local<S> that) { 276 #ifdef V8_ENABLE_CHECKS 277 // If we're going to perform the type check then we have to check 278 // that the handle isn't empty before doing the checked cast. 279 if (that.IsEmpty()) return Local<T>(); 280 #endif 281 return Local<T>(T::Cast(*that)); 282 } 283 284 template <class S> inline Local<S> As() { 285 return Local<S>::Cast(*this); 286 } 287 288 /** Create a local handle for the content of another handle. 289 * The referee is kept alive by the local handle even when 290 * the original handle is destroyed/disposed. 291 */ 292 inline static Local<T> New(Handle<T> that); 293 }; 294 295 296 /** 297 * An object reference that is independent of any handle scope. Where 298 * a Local handle only lives as long as the HandleScope in which it was 299 * allocated, a Persistent handle remains valid until it is explicitly 300 * disposed. 301 * 302 * A persistent handle contains a reference to a storage cell within 303 * the v8 engine which holds an object value and which is updated by 304 * the garbage collector whenever the object is moved. A new storage 305 * cell can be created using Persistent::New and existing handles can 306 * be disposed using Persistent::Dispose. Since persistent handles 307 * are passed by value you may have many persistent handle objects 308 * that point to the same storage cell. For instance, if you pass a 309 * persistent handle as an argument to a function you will not get two 310 * different storage cells but rather two references to the same 311 * storage cell. 312 */ 313 template <class T> class Persistent : public Handle<T> { 314 public: 315 316 /** 317 * Creates an empty persistent handle that doesn't point to any 318 * storage cell. 319 */ 320 inline Persistent(); 321 322 /** 323 * Creates a persistent handle for the same storage cell as the 324 * specified handle. This constructor allows you to pass persistent 325 * handles as arguments by value and to assign between persistent 326 * handles. However, attempting to assign between incompatible 327 * persistent handles, for instance from a Persistent<String> to a 328 * Persistent<Number> will cause a compiletime error. Assigning 329 * between compatible persistent handles, for instance assigning a 330 * Persistent<String> to a variable declared as Persistent<Value>, 331 * is allowed as String is a subclass of Value. 332 */ 333 template <class S> inline Persistent(Persistent<S> that) 334 : Handle<T>(reinterpret_cast<T*>(*that)) { 335 /** 336 * This check fails when trying to convert between incompatible 337 * handles. For example, converting from a Handle<String> to a 338 * Handle<Number>. 339 */ 340 TYPE_CHECK(T, S); 341 } 342 343 template <class S> inline Persistent(S* that) : Handle<T>(that) { } 344 345 /** 346 * "Casts" a plain handle which is known to be a persistent handle 347 * to a persistent handle. 348 */ 349 template <class S> explicit inline Persistent(Handle<S> that) 350 : Handle<T>(*that) { } 351 352 template <class S> static inline Persistent<T> Cast(Persistent<S> that) { 353 #ifdef V8_ENABLE_CHECKS 354 // If we're going to perform the type check then we have to check 355 // that the handle isn't empty before doing the checked cast. 356 if (that.IsEmpty()) return Persistent<T>(); 357 #endif 358 return Persistent<T>(T::Cast(*that)); 359 } 360 361 template <class S> inline Persistent<S> As() { 362 return Persistent<S>::Cast(*this); 363 } 364 365 /** 366 * Creates a new persistent handle for an existing local or 367 * persistent handle. 368 */ 369 inline static Persistent<T> New(Handle<T> that); 370 371 /** 372 * Releases the storage cell referenced by this persistent handle. 373 * Does not remove the reference to the cell from any handles. 374 * This handle's reference, and any any other references to the storage 375 * cell remain and IsEmpty will still return false. 376 */ 377 inline void Dispose(); 378 379 /** 380 * Make the reference to this object weak. When only weak handles 381 * refer to the object, the garbage collector will perform a 382 * callback to the given V8::WeakReferenceCallback function, passing 383 * it the object reference and the given parameters. 384 */ 385 inline void MakeWeak(void* parameters, WeakReferenceCallback callback); 386 387 /** Clears the weak reference to this object.*/ 388 inline void ClearWeak(); 389 390 /** 391 *Checks if the handle holds the only reference to an object. 392 */ 393 inline bool IsNearDeath() const; 394 395 /** 396 * Returns true if the handle's reference is weak. 397 */ 398 inline bool IsWeak() const; 399 400 /** 401 * Assigns a wrapper class ID to the handle. See RetainedObjectInfo 402 * interface description in v8-profiler.h for details. 403 */ 404 inline void SetWrapperClassId(uint16_t class_id); 405 406 private: 407 friend class ImplementationUtilities; 408 friend class ObjectTemplate; 409 }; 410 411 412 /** 413 * A stack-allocated class that governs a number of local handles. 414 * After a handle scope has been created, all local handles will be 415 * allocated within that handle scope until either the handle scope is 416 * deleted or another handle scope is created. If there is already a 417 * handle scope and a new one is created, all allocations will take 418 * place in the new handle scope until it is deleted. After that, 419 * new handles will again be allocated in the original handle scope. 420 * 421 * After the handle scope of a local handle has been deleted the 422 * garbage collector will no longer track the object stored in the 423 * handle and may deallocate it. The behavior of accessing a handle 424 * for which the handle scope has been deleted is undefined. 425 */ 426 class V8EXPORT HandleScope { 427 public: 428 HandleScope(); 429 430 ~HandleScope(); 431 432 /** 433 * Closes the handle scope and returns the value as a handle in the 434 * previous scope, which is the new current scope after the call. 435 */ 436 template <class T> Local<T> Close(Handle<T> value); 437 438 /** 439 * Counts the number of allocated handles. 440 */ 441 static int NumberOfHandles(); 442 443 /** 444 * Creates a new handle with the given value. 445 */ 446 static internal::Object** CreateHandle(internal::Object* value); 447 // Faster version, uses HeapObject to obtain the current Isolate. 448 static internal::Object** CreateHandle(internal::HeapObject* value); 449 450 private: 451 // Make it impossible to create heap-allocated or illegal handle 452 // scopes by disallowing certain operations. 453 HandleScope(const HandleScope&); 454 void operator=(const HandleScope&); 455 void* operator new(size_t size); 456 void operator delete(void*, size_t); 457 458 // This Data class is accessible internally as HandleScopeData through a 459 // typedef in the ImplementationUtilities class. 460 class V8EXPORT Data { 461 public: 462 internal::Object** next; 463 internal::Object** limit; 464 int level; 465 inline void Initialize() { 466 next = limit = NULL; 467 level = 0; 468 } 469 }; 470 471 void Leave(); 472 473 internal::Isolate* isolate_; 474 internal::Object** prev_next_; 475 internal::Object** prev_limit_; 476 477 // Allow for the active closing of HandleScopes which allows to pass a handle 478 // from the HandleScope being closed to the next top most HandleScope. 479 bool is_closed_; 480 internal::Object** RawClose(internal::Object** value); 481 482 friend class ImplementationUtilities; 483 }; 484 485 486 // --- S p e c i a l o b j e c t s --- 487 488 489 /** 490 * The superclass of values and API object templates. 491 */ 492 class V8EXPORT Data { 493 private: 494 Data(); 495 }; 496 497 498 /** 499 * Pre-compilation data that can be associated with a script. This 500 * data can be calculated for a script in advance of actually 501 * compiling it, and can be stored between compilations. When script 502 * data is given to the compile method compilation will be faster. 503 */ 504 class V8EXPORT ScriptData { // NOLINT 505 public: 506 virtual ~ScriptData() { } 507 508 /** 509 * Pre-compiles the specified script (context-independent). 510 * 511 * \param input Pointer to UTF-8 script source code. 512 * \param length Length of UTF-8 script source code. 513 */ 514 static ScriptData* PreCompile(const char* input, int length); 515 516 /** 517 * Pre-compiles the specified script (context-independent). 518 * 519 * NOTE: Pre-compilation using this method cannot happen on another thread 520 * without using Lockers. 521 * 522 * \param source Script source code. 523 */ 524 static ScriptData* PreCompile(Handle<String> source); 525 526 /** 527 * Load previous pre-compilation data. 528 * 529 * \param data Pointer to data returned by a call to Data() of a previous 530 * ScriptData. Ownership is not transferred. 531 * \param length Length of data. 532 */ 533 static ScriptData* New(const char* data, int length); 534 535 /** 536 * Returns the length of Data(). 537 */ 538 virtual int Length() = 0; 539 540 /** 541 * Returns a serialized representation of this ScriptData that can later be 542 * passed to New(). NOTE: Serialized data is platform-dependent. 543 */ 544 virtual const char* Data() = 0; 545 546 /** 547 * Returns true if the source code could not be parsed. 548 */ 549 virtual bool HasError() = 0; 550 }; 551 552 553 /** 554 * The origin, within a file, of a script. 555 */ 556 class ScriptOrigin { 557 public: 558 inline ScriptOrigin( 559 Handle<Value> resource_name, 560 Handle<Integer> resource_line_offset = Handle<Integer>(), 561 Handle<Integer> resource_column_offset = Handle<Integer>()) 562 : resource_name_(resource_name), 563 resource_line_offset_(resource_line_offset), 564 resource_column_offset_(resource_column_offset) { } 565 inline Handle<Value> ResourceName() const; 566 inline Handle<Integer> ResourceLineOffset() const; 567 inline Handle<Integer> ResourceColumnOffset() const; 568 private: 569 Handle<Value> resource_name_; 570 Handle<Integer> resource_line_offset_; 571 Handle<Integer> resource_column_offset_; 572 }; 573 574 575 /** 576 * A compiled JavaScript script. 577 */ 578 class V8EXPORT Script { 579 public: 580 581 /** 582 * Compiles the specified script (context-independent). 583 * 584 * \param source Script source code. 585 * \param origin Script origin, owned by caller, no references are kept 586 * when New() returns 587 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile() 588 * using pre_data speeds compilation if it's done multiple times. 589 * Owned by caller, no references are kept when New() returns. 590 * \param script_data Arbitrary data associated with script. Using 591 * this has same effect as calling SetData(), but allows data to be 592 * available to compile event handlers. 593 * \return Compiled script object (context independent; when run it 594 * will use the currently entered context). 595 */ 596 static Local<Script> New(Handle<String> source, 597 ScriptOrigin* origin = NULL, 598 ScriptData* pre_data = NULL, 599 Handle<String> script_data = Handle<String>()); 600 601 /** 602 * Compiles the specified script using the specified file name 603 * object (typically a string) as the script's origin. 604 * 605 * \param source Script source code. 606 * \param file_name file name object (typically a string) to be used 607 * as the script's origin. 608 * \return Compiled script object (context independent; when run it 609 * will use the currently entered context). 610 */ 611 static Local<Script> New(Handle<String> source, 612 Handle<Value> file_name); 613 614 /** 615 * Compiles the specified script (bound to current context). 616 * 617 * \param source Script source code. 618 * \param origin Script origin, owned by caller, no references are kept 619 * when Compile() returns 620 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile() 621 * using pre_data speeds compilation if it's done multiple times. 622 * Owned by caller, no references are kept when Compile() returns. 623 * \param script_data Arbitrary data associated with script. Using 624 * this has same effect as calling SetData(), but makes data available 625 * earlier (i.e. to compile event handlers). 626 * \return Compiled script object, bound to the context that was active 627 * when this function was called. When run it will always use this 628 * context. 629 */ 630 static Local<Script> Compile(Handle<String> source, 631 ScriptOrigin* origin = NULL, 632 ScriptData* pre_data = NULL, 633 Handle<String> script_data = Handle<String>()); 634 635 /** 636 * Compiles the specified script using the specified file name 637 * object (typically a string) as the script's origin. 638 * 639 * \param source Script source code. 640 * \param file_name File name to use as script's origin 641 * \param script_data Arbitrary data associated with script. Using 642 * this has same effect as calling SetData(), but makes data available 643 * earlier (i.e. to compile event handlers). 644 * \return Compiled script object, bound to the context that was active 645 * when this function was called. When run it will always use this 646 * context. 647 */ 648 static Local<Script> Compile(Handle<String> source, 649 Handle<Value> file_name, 650 Handle<String> script_data = Handle<String>()); 651 652 /** 653 * Runs the script returning the resulting value. If the script is 654 * context independent (created using ::New) it will be run in the 655 * currently entered context. If it is context specific (created 656 * using ::Compile) it will be run in the context in which it was 657 * compiled. 658 */ 659 Local<Value> Run(); 660 661 /** 662 * Returns the script id value. 663 */ 664 Local<Value> Id(); 665 666 /** 667 * Associate an additional data object with the script. This is mainly used 668 * with the debugger as this data object is only available through the 669 * debugger API. 670 */ 671 void SetData(Handle<String> data); 672 }; 673 674 675 /** 676 * An error message. 677 */ 678 class V8EXPORT Message { 679 public: 680 Local<String> Get() const; 681 Local<String> GetSourceLine() const; 682 683 /** 684 * Returns the resource name for the script from where the function causing 685 * the error originates. 686 */ 687 Handle<Value> GetScriptResourceName() const; 688 689 /** 690 * Returns the resource data for the script from where the function causing 691 * the error originates. 692 */ 693 Handle<Value> GetScriptData() const; 694 695 /** 696 * Exception stack trace. By default stack traces are not captured for 697 * uncaught exceptions. SetCaptureStackTraceForUncaughtExceptions allows 698 * to change this option. 699 */ 700 Handle<StackTrace> GetStackTrace() const; 701 702 /** 703 * Returns the number, 1-based, of the line where the error occurred. 704 */ 705 int GetLineNumber() const; 706 707 /** 708 * Returns the index within the script of the first character where 709 * the error occurred. 710 */ 711 int GetStartPosition() const; 712 713 /** 714 * Returns the index within the script of the last character where 715 * the error occurred. 716 */ 717 int GetEndPosition() const; 718 719 /** 720 * Returns the index within the line of the first character where 721 * the error occurred. 722 */ 723 int GetStartColumn() const; 724 725 /** 726 * Returns the index within the line of the last character where 727 * the error occurred. 728 */ 729 int GetEndColumn() const; 730 731 // TODO(1245381): Print to a string instead of on a FILE. 732 static void PrintCurrentStackTrace(FILE* out); 733 734 static const int kNoLineNumberInfo = 0; 735 static const int kNoColumnInfo = 0; 736 }; 737 738 739 /** 740 * Representation of a JavaScript stack trace. The information collected is a 741 * snapshot of the execution stack and the information remains valid after 742 * execution continues. 743 */ 744 class V8EXPORT StackTrace { 745 public: 746 /** 747 * Flags that determine what information is placed captured for each 748 * StackFrame when grabbing the current stack trace. 749 */ 750 enum StackTraceOptions { 751 kLineNumber = 1, 752 kColumnOffset = 1 << 1 | kLineNumber, 753 kScriptName = 1 << 2, 754 kFunctionName = 1 << 3, 755 kIsEval = 1 << 4, 756 kIsConstructor = 1 << 5, 757 kScriptNameOrSourceURL = 1 << 6, 758 kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName, 759 kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL 760 }; 761 762 /** 763 * Returns a StackFrame at a particular index. 764 */ 765 Local<StackFrame> GetFrame(uint32_t index) const; 766 767 /** 768 * Returns the number of StackFrames. 769 */ 770 int GetFrameCount() const; 771 772 /** 773 * Returns StackTrace as a v8::Array that contains StackFrame objects. 774 */ 775 Local<Array> AsArray(); 776 777 /** 778 * Grab a snapshot of the the current JavaScript execution stack. 779 * 780 * \param frame_limit The maximum number of stack frames we want to capture. 781 * \param options Enumerates the set of things we will capture for each 782 * StackFrame. 783 */ 784 static Local<StackTrace> CurrentStackTrace( 785 int frame_limit, 786 StackTraceOptions options = kOverview); 787 }; 788 789 790 /** 791 * A single JavaScript stack frame. 792 */ 793 class V8EXPORT StackFrame { 794 public: 795 /** 796 * Returns the number, 1-based, of the line for the associate function call. 797 * This method will return Message::kNoLineNumberInfo if it is unable to 798 * retrieve the line number, or if kLineNumber was not passed as an option 799 * when capturing the StackTrace. 800 */ 801 int GetLineNumber() const; 802 803 /** 804 * Returns the 1-based column offset on the line for the associated function 805 * call. 806 * This method will return Message::kNoColumnInfo if it is unable to retrieve 807 * the column number, or if kColumnOffset was not passed as an option when 808 * capturing the StackTrace. 809 */ 810 int GetColumn() const; 811 812 /** 813 * Returns the name of the resource that contains the script for the 814 * function for this StackFrame. 815 */ 816 Local<String> GetScriptName() const; 817 818 /** 819 * Returns the name of the resource that contains the script for the 820 * function for this StackFrame or sourceURL value if the script name 821 * is undefined and its source ends with //@ sourceURL=... string. 822 */ 823 Local<String> GetScriptNameOrSourceURL() const; 824 825 /** 826 * Returns the name of the function associated with this stack frame. 827 */ 828 Local<String> GetFunctionName() const; 829 830 /** 831 * Returns whether or not the associated function is compiled via a call to 832 * eval(). 833 */ 834 bool IsEval() const; 835 836 /** 837 * Returns whther or not the associated function is called as a 838 * constructor via "new". 839 */ 840 bool IsConstructor() const; 841 }; 842 843 844 // --- V a l u e --- 845 846 847 /** 848 * The superclass of all JavaScript values and objects. 849 */ 850 class Value : public Data { 851 public: 852 853 /** 854 * Returns true if this value is the undefined value. See ECMA-262 855 * 4.3.10. 856 */ 857 V8EXPORT bool IsUndefined() const; 858 859 /** 860 * Returns true if this value is the null value. See ECMA-262 861 * 4.3.11. 862 */ 863 V8EXPORT bool IsNull() const; 864 865 /** 866 * Returns true if this value is true. 867 */ 868 V8EXPORT bool IsTrue() const; 869 870 /** 871 * Returns true if this value is false. 872 */ 873 V8EXPORT bool IsFalse() const; 874 875 /** 876 * Returns true if this value is an instance of the String type. 877 * See ECMA-262 8.4. 878 */ 879 inline bool IsString() const; 880 881 /** 882 * Returns true if this value is a function. 883 */ 884 V8EXPORT bool IsFunction() const; 885 886 /** 887 * Returns true if this value is an array. 888 */ 889 V8EXPORT bool IsArray() const; 890 891 /** 892 * Returns true if this value is an object. 893 */ 894 V8EXPORT bool IsObject() const; 895 896 /** 897 * Returns true if this value is boolean. 898 */ 899 V8EXPORT bool IsBoolean() const; 900 901 /** 902 * Returns true if this value is a number. 903 */ 904 V8EXPORT bool IsNumber() const; 905 906 /** 907 * Returns true if this value is external. 908 */ 909 V8EXPORT bool IsExternal() const; 910 911 /** 912 * Returns true if this value is a 32-bit signed integer. 913 */ 914 V8EXPORT bool IsInt32() const; 915 916 /** 917 * Returns true if this value is a 32-bit unsigned integer. 918 */ 919 V8EXPORT bool IsUint32() const; 920 921 /** 922 * Returns true if this value is a Date. 923 */ 924 V8EXPORT bool IsDate() const; 925 926 /** 927 * Returns true if this value is a RegExp. 928 */ 929 V8EXPORT bool IsRegExp() const; 930 931 V8EXPORT Local<Boolean> ToBoolean() const; 932 V8EXPORT Local<Number> ToNumber() const; 933 V8EXPORT Local<String> ToString() const; 934 V8EXPORT Local<String> ToDetailString() const; 935 V8EXPORT Local<Object> ToObject() const; 936 V8EXPORT Local<Integer> ToInteger() const; 937 V8EXPORT Local<Uint32> ToUint32() const; 938 V8EXPORT Local<Int32> ToInt32() const; 939 940 /** 941 * Attempts to convert a string to an array index. 942 * Returns an empty handle if the conversion fails. 943 */ 944 V8EXPORT Local<Uint32> ToArrayIndex() const; 945 946 V8EXPORT bool BooleanValue() const; 947 V8EXPORT double NumberValue() const; 948 V8EXPORT int64_t IntegerValue() const; 949 V8EXPORT uint32_t Uint32Value() const; 950 V8EXPORT int32_t Int32Value() const; 951 952 /** JS == */ 953 V8EXPORT bool Equals(Handle<Value> that) const; 954 V8EXPORT bool StrictEquals(Handle<Value> that) const; 955 956 private: 957 inline bool QuickIsString() const; 958 V8EXPORT bool FullIsString() const; 959 }; 960 961 962 /** 963 * The superclass of primitive values. See ECMA-262 4.3.2. 964 */ 965 class Primitive : public Value { }; 966 967 968 /** 969 * A primitive boolean value (ECMA-262, 4.3.14). Either the true 970 * or false value. 971 */ 972 class Boolean : public Primitive { 973 public: 974 V8EXPORT bool Value() const; 975 static inline Handle<Boolean> New(bool value); 976 }; 977 978 979 /** 980 * A JavaScript string value (ECMA-262, 4.3.17). 981 */ 982 class String : public Primitive { 983 public: 984 985 /** 986 * Returns the number of characters in this string. 987 */ 988 V8EXPORT int Length() const; 989 990 /** 991 * Returns the number of bytes in the UTF-8 encoded 992 * representation of this string. 993 */ 994 V8EXPORT int Utf8Length() const; 995 996 /** 997 * Write the contents of the string to an external buffer. 998 * If no arguments are given, expects the buffer to be large 999 * enough to hold the entire string and NULL terminator. Copies 1000 * the contents of the string and the NULL terminator into the 1001 * buffer. 1002 * 1003 * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop 1004 * before the end of the buffer. 1005 * 1006 * Copies up to length characters into the output buffer. 1007 * Only null-terminates if there is enough space in the buffer. 1008 * 1009 * \param buffer The buffer into which the string will be copied. 1010 * \param start The starting position within the string at which 1011 * copying begins. 1012 * \param length The number of characters to copy from the string. For 1013 * WriteUtf8 the number of bytes in the buffer. 1014 * \param nchars_ref The number of characters written, can be NULL. 1015 * \param hints Various hints that might affect performance of this or 1016 * subsequent operations. 1017 * \return The number of characters copied to the buffer excluding the null 1018 * terminator. For WriteUtf8: The number of bytes copied to the buffer 1019 * including the null terminator. 1020 */ 1021 enum WriteHints { 1022 NO_HINTS = 0, 1023 HINT_MANY_WRITES_EXPECTED = 1 1024 }; 1025 1026 V8EXPORT int Write(uint16_t* buffer, 1027 int start = 0, 1028 int length = -1, 1029 WriteHints hints = NO_HINTS) const; // UTF-16 1030 V8EXPORT int WriteAscii(char* buffer, 1031 int start = 0, 1032 int length = -1, 1033 WriteHints hints = NO_HINTS) const; // ASCII 1034 V8EXPORT int WriteUtf8(char* buffer, 1035 int length = -1, 1036 int* nchars_ref = NULL, 1037 WriteHints hints = NO_HINTS) const; // UTF-8 1038 1039 /** 1040 * A zero length string. 1041 */ 1042 V8EXPORT static v8::Local<v8::String> Empty(); 1043 1044 /** 1045 * Returns true if the string is external 1046 */ 1047 V8EXPORT bool IsExternal() const; 1048 1049 /** 1050 * Returns true if the string is both external and ascii 1051 */ 1052 V8EXPORT bool IsExternalAscii() const; 1053 1054 class V8EXPORT ExternalStringResourceBase { // NOLINT 1055 public: 1056 virtual ~ExternalStringResourceBase() {} 1057 1058 protected: 1059 ExternalStringResourceBase() {} 1060 1061 /** 1062 * Internally V8 will call this Dispose method when the external string 1063 * resource is no longer needed. The default implementation will use the 1064 * delete operator. This method can be overridden in subclasses to 1065 * control how allocated external string resources are disposed. 1066 */ 1067 virtual void Dispose() { delete this; } 1068 1069 private: 1070 // Disallow copying and assigning. 1071 ExternalStringResourceBase(const ExternalStringResourceBase&); 1072 void operator=(const ExternalStringResourceBase&); 1073 1074 friend class v8::internal::Heap; 1075 }; 1076 1077 /** 1078 * An ExternalStringResource is a wrapper around a two-byte string 1079 * buffer that resides outside V8's heap. Implement an 1080 * ExternalStringResource to manage the life cycle of the underlying 1081 * buffer. Note that the string data must be immutable. 1082 */ 1083 class V8EXPORT ExternalStringResource 1084 : public ExternalStringResourceBase { 1085 public: 1086 /** 1087 * Override the destructor to manage the life cycle of the underlying 1088 * buffer. 1089 */ 1090 virtual ~ExternalStringResource() {} 1091 1092 /** 1093 * The string data from the underlying buffer. 1094 */ 1095 virtual const uint16_t* data() const = 0; 1096 1097 /** 1098 * The length of the string. That is, the number of two-byte characters. 1099 */ 1100 virtual size_t length() const = 0; 1101 1102 protected: 1103 ExternalStringResource() {} 1104 }; 1105 1106 /** 1107 * An ExternalAsciiStringResource is a wrapper around an ascii 1108 * string buffer that resides outside V8's heap. Implement an 1109 * ExternalAsciiStringResource to manage the life cycle of the 1110 * underlying buffer. Note that the string data must be immutable 1111 * and that the data must be strict 7-bit ASCII, not Latin1 or 1112 * UTF-8, which would require special treatment internally in the 1113 * engine and, in the case of UTF-8, do not allow efficient indexing. 1114 * Use String::New or convert to 16 bit data for non-ASCII. 1115 */ 1116 1117 class V8EXPORT ExternalAsciiStringResource 1118 : public ExternalStringResourceBase { 1119 public: 1120 /** 1121 * Override the destructor to manage the life cycle of the underlying 1122 * buffer. 1123 */ 1124 virtual ~ExternalAsciiStringResource() {} 1125 /** The string data from the underlying buffer.*/ 1126 virtual const char* data() const = 0; 1127 /** The number of ascii characters in the string.*/ 1128 virtual size_t length() const = 0; 1129 protected: 1130 ExternalAsciiStringResource() {} 1131 }; 1132 1133 /** 1134 * Get the ExternalStringResource for an external string. Returns 1135 * NULL if IsExternal() doesn't return true. 1136 */ 1137 inline ExternalStringResource* GetExternalStringResource() const; 1138 1139 /** 1140 * Get the ExternalAsciiStringResource for an external ascii string. 1141 * Returns NULL if IsExternalAscii() doesn't return true. 1142 */ 1143 V8EXPORT ExternalAsciiStringResource* GetExternalAsciiStringResource() const; 1144 1145 static inline String* Cast(v8::Value* obj); 1146 1147 /** 1148 * Allocates a new string from either utf-8 encoded or ascii data. 1149 * The second parameter 'length' gives the buffer length. 1150 * If the data is utf-8 encoded, the caller must 1151 * be careful to supply the length parameter. 1152 * If it is not given, the function calls 1153 * 'strlen' to determine the buffer length, it might be 1154 * wrong if 'data' contains a null character. 1155 */ 1156 V8EXPORT static Local<String> New(const char* data, int length = -1); 1157 1158 /** Allocates a new string from utf16 data.*/ 1159 V8EXPORT static Local<String> New(const uint16_t* data, int length = -1); 1160 1161 /** Creates a symbol. Returns one if it exists already.*/ 1162 V8EXPORT static Local<String> NewSymbol(const char* data, int length = -1); 1163 1164 /** 1165 * Creates a new string by concatenating the left and the right strings 1166 * passed in as parameters. 1167 */ 1168 V8EXPORT static Local<String> Concat(Handle<String> left, 1169 Handle<String>right); 1170 1171 /** 1172 * Creates a new external string using the data defined in the given 1173 * resource. When the external string is no longer live on V8's heap the 1174 * resource will be disposed by calling its Dispose method. The caller of 1175 * this function should not otherwise delete or modify the resource. Neither 1176 * should the underlying buffer be deallocated or modified except through the 1177 * destructor of the external string resource. 1178 */ 1179 V8EXPORT static Local<String> NewExternal(ExternalStringResource* resource); 1180 1181 /** 1182 * Associate an external string resource with this string by transforming it 1183 * in place so that existing references to this string in the JavaScript heap 1184 * will use the external string resource. The external string resource's 1185 * character contents needs to be equivalent to this string. 1186 * Returns true if the string has been changed to be an external string. 1187 * The string is not modified if the operation fails. See NewExternal for 1188 * information on the lifetime of the resource. 1189 */ 1190 V8EXPORT bool MakeExternal(ExternalStringResource* resource); 1191 1192 /** 1193 * Creates a new external string using the ascii data defined in the given 1194 * resource. When the external string is no longer live on V8's heap the 1195 * resource will be disposed by calling its Dispose method. The caller of 1196 * this function should not otherwise delete or modify the resource. Neither 1197 * should the underlying buffer be deallocated or modified except through the 1198 * destructor of the external string resource. 1199 */ 1200 V8EXPORT static Local<String> NewExternal( 1201 ExternalAsciiStringResource* resource); 1202 1203 /** 1204 * Associate an external string resource with this string by transforming it 1205 * in place so that existing references to this string in the JavaScript heap 1206 * will use the external string resource. The external string resource's 1207 * character contents needs to be equivalent to this string. 1208 * Returns true if the string has been changed to be an external string. 1209 * The string is not modified if the operation fails. See NewExternal for 1210 * information on the lifetime of the resource. 1211 */ 1212 V8EXPORT bool MakeExternal(ExternalAsciiStringResource* resource); 1213 1214 /** 1215 * Returns true if this string can be made external. 1216 */ 1217 V8EXPORT bool CanMakeExternal(); 1218 1219 /** Creates an undetectable string from the supplied ascii or utf-8 data.*/ 1220 V8EXPORT static Local<String> NewUndetectable(const char* data, 1221 int length = -1); 1222 1223 /** Creates an undetectable string from the supplied utf-16 data.*/ 1224 V8EXPORT static Local<String> NewUndetectable(const uint16_t* data, 1225 int length = -1); 1226 1227 /** 1228 * Converts an object to a utf8-encoded character array. Useful if 1229 * you want to print the object. If conversion to a string fails 1230 * (eg. due to an exception in the toString() method of the object) 1231 * then the length() method returns 0 and the * operator returns 1232 * NULL. 1233 */ 1234 class V8EXPORT Utf8Value { 1235 public: 1236 explicit Utf8Value(Handle<v8::Value> obj); 1237 ~Utf8Value(); 1238 char* operator*() { return str_; } 1239 const char* operator*() const { return str_; } 1240 int length() const { return length_; } 1241 private: 1242 char* str_; 1243 int length_; 1244 1245 // Disallow copying and assigning. 1246 Utf8Value(const Utf8Value&); 1247 void operator=(const Utf8Value&); 1248 }; 1249 1250 /** 1251 * Converts an object to an ascii string. 1252 * Useful if you want to print the object. 1253 * If conversion to a string fails (eg. due to an exception in the toString() 1254 * method of the object) then the length() method returns 0 and the * operator 1255 * returns NULL. 1256 */ 1257 class V8EXPORT AsciiValue { 1258 public: 1259 explicit AsciiValue(Handle<v8::Value> obj); 1260 ~AsciiValue(); 1261 char* operator*() { return str_; } 1262 const char* operator*() const { return str_; } 1263 int length() const { return length_; } 1264 private: 1265 char* str_; 1266 int length_; 1267 1268 // Disallow copying and assigning. 1269 AsciiValue(const AsciiValue&); 1270 void operator=(const AsciiValue&); 1271 }; 1272 1273 /** 1274 * Converts an object to a two-byte string. 1275 * If conversion to a string fails (eg. due to an exception in the toString() 1276 * method of the object) then the length() method returns 0 and the * operator 1277 * returns NULL. 1278 */ 1279 class V8EXPORT Value { 1280 public: 1281 explicit Value(Handle<v8::Value> obj); 1282 ~Value(); 1283 uint16_t* operator*() { return str_; } 1284 const uint16_t* operator*() const { return str_; } 1285 int length() const { return length_; } 1286 private: 1287 uint16_t* str_; 1288 int length_; 1289 1290 // Disallow copying and assigning. 1291 Value(const Value&); 1292 void operator=(const Value&); 1293 }; 1294 1295 private: 1296 V8EXPORT void VerifyExternalStringResource(ExternalStringResource* val) const; 1297 V8EXPORT static void CheckCast(v8::Value* obj); 1298 }; 1299 1300 1301 /** 1302 * A JavaScript number value (ECMA-262, 4.3.20) 1303 */ 1304 class Number : public Primitive { 1305 public: 1306 V8EXPORT double Value() const; 1307 V8EXPORT static Local<Number> New(double value); 1308 static inline Number* Cast(v8::Value* obj); 1309 private: 1310 V8EXPORT Number(); 1311 static void CheckCast(v8::Value* obj); 1312 }; 1313 1314 1315 /** 1316 * A JavaScript value representing a signed integer. 1317 */ 1318 class Integer : public Number { 1319 public: 1320 V8EXPORT static Local<Integer> New(int32_t value); 1321 V8EXPORT static Local<Integer> NewFromUnsigned(uint32_t value); 1322 V8EXPORT int64_t Value() const; 1323 static inline Integer* Cast(v8::Value* obj); 1324 private: 1325 V8EXPORT Integer(); 1326 V8EXPORT static void CheckCast(v8::Value* obj); 1327 }; 1328 1329 1330 /** 1331 * A JavaScript value representing a 32-bit signed integer. 1332 */ 1333 class Int32 : public Integer { 1334 public: 1335 V8EXPORT int32_t Value() const; 1336 private: 1337 V8EXPORT Int32(); 1338 }; 1339 1340 1341 /** 1342 * A JavaScript value representing a 32-bit unsigned integer. 1343 */ 1344 class Uint32 : public Integer { 1345 public: 1346 V8EXPORT uint32_t Value() const; 1347 private: 1348 V8EXPORT Uint32(); 1349 }; 1350 1351 1352 /** 1353 * An instance of the built-in Date constructor (ECMA-262, 15.9). 1354 */ 1355 class Date : public Value { 1356 public: 1357 V8EXPORT static Local<Value> New(double time); 1358 1359 /** 1360 * A specialization of Value::NumberValue that is more efficient 1361 * because we know the structure of this object. 1362 */ 1363 V8EXPORT double NumberValue() const; 1364 1365 static inline Date* Cast(v8::Value* obj); 1366 1367 /** 1368 * Notification that the embedder has changed the time zone, 1369 * daylight savings time, or other date / time configuration 1370 * parameters. V8 keeps a cache of various values used for 1371 * date / time computation. This notification will reset 1372 * those cached values for the current context so that date / 1373 * time configuration changes would be reflected in the Date 1374 * object. 1375 * 1376 * This API should not be called more than needed as it will 1377 * negatively impact the performance of date operations. 1378 */ 1379 V8EXPORT static void DateTimeConfigurationChangeNotification(); 1380 1381 private: 1382 V8EXPORT static void CheckCast(v8::Value* obj); 1383 }; 1384 1385 1386 /** 1387 * An instance of the built-in RegExp constructor (ECMA-262, 15.10). 1388 */ 1389 class RegExp : public Value { 1390 public: 1391 /** 1392 * Regular expression flag bits. They can be or'ed to enable a set 1393 * of flags. 1394 */ 1395 enum Flags { 1396 kNone = 0, 1397 kGlobal = 1, 1398 kIgnoreCase = 2, 1399 kMultiline = 4 1400 }; 1401 1402 /** 1403 * Creates a regular expression from the given pattern string and 1404 * the flags bit field. May throw a JavaScript exception as 1405 * described in ECMA-262, 15.10.4.1. 1406 * 1407 * For example, 1408 * RegExp::New(v8::String::New("foo"), 1409 * static_cast<RegExp::Flags>(kGlobal | kMultiline)) 1410 * is equivalent to evaluating "/foo/gm". 1411 */ 1412 V8EXPORT static Local<RegExp> New(Handle<String> pattern, 1413 Flags flags); 1414 1415 /** 1416 * Returns the value of the source property: a string representing 1417 * the regular expression. 1418 */ 1419 V8EXPORT Local<String> GetSource() const; 1420 1421 /** 1422 * Returns the flags bit field. 1423 */ 1424 V8EXPORT Flags GetFlags() const; 1425 1426 static inline RegExp* Cast(v8::Value* obj); 1427 1428 private: 1429 V8EXPORT static void CheckCast(v8::Value* obj); 1430 }; 1431 1432 1433 enum PropertyAttribute { 1434 None = 0, 1435 ReadOnly = 1 << 0, 1436 DontEnum = 1 << 1, 1437 DontDelete = 1 << 2 1438 }; 1439 1440 enum ExternalArrayType { 1441 kExternalByteArray = 1, 1442 kExternalUnsignedByteArray, 1443 kExternalShortArray, 1444 kExternalUnsignedShortArray, 1445 kExternalIntArray, 1446 kExternalUnsignedIntArray, 1447 kExternalFloatArray, 1448 kExternalPixelArray 1449 }; 1450 1451 /** 1452 * Accessor[Getter|Setter] are used as callback functions when 1453 * setting|getting a particular property. See Object and ObjectTemplate's 1454 * method SetAccessor. 1455 */ 1456 typedef Handle<Value> (*AccessorGetter)(Local<String> property, 1457 const AccessorInfo& info); 1458 1459 1460 typedef void (*AccessorSetter)(Local<String> property, 1461 Local<Value> value, 1462 const AccessorInfo& info); 1463 1464 1465 /** 1466 * Access control specifications. 1467 * 1468 * Some accessors should be accessible across contexts. These 1469 * accessors have an explicit access control parameter which specifies 1470 * the kind of cross-context access that should be allowed. 1471 * 1472 * Additionally, for security, accessors can prohibit overwriting by 1473 * accessors defined in JavaScript. For objects that have such 1474 * accessors either locally or in their prototype chain it is not 1475 * possible to overwrite the accessor by using __defineGetter__ or 1476 * __defineSetter__ from JavaScript code. 1477 */ 1478 enum AccessControl { 1479 DEFAULT = 0, 1480 ALL_CAN_READ = 1, 1481 ALL_CAN_WRITE = 1 << 1, 1482 PROHIBITS_OVERWRITING = 1 << 2 1483 }; 1484 1485 1486 /** 1487 * A JavaScript object (ECMA-262, 4.3.3) 1488 */ 1489 class Object : public Value { 1490 public: 1491 V8EXPORT bool Set(Handle<Value> key, 1492 Handle<Value> value, 1493 PropertyAttribute attribs = None); 1494 1495 V8EXPORT bool Set(uint32_t index, 1496 Handle<Value> value); 1497 1498 // Sets a local property on this object bypassing interceptors and 1499 // overriding accessors or read-only properties. 1500 // 1501 // Note that if the object has an interceptor the property will be set 1502 // locally, but since the interceptor takes precedence the local property 1503 // will only be returned if the interceptor doesn't return a value. 1504 // 1505 // Note also that this only works for named properties. 1506 V8EXPORT bool ForceSet(Handle<Value> key, 1507 Handle<Value> value, 1508 PropertyAttribute attribs = None); 1509 1510 V8EXPORT Local<Value> Get(Handle<Value> key); 1511 1512 V8EXPORT Local<Value> Get(uint32_t index); 1513 1514 // TODO(1245389): Replace the type-specific versions of these 1515 // functions with generic ones that accept a Handle<Value> key. 1516 V8EXPORT bool Has(Handle<String> key); 1517 1518 V8EXPORT bool Delete(Handle<String> key); 1519 1520 // Delete a property on this object bypassing interceptors and 1521 // ignoring dont-delete attributes. 1522 V8EXPORT bool ForceDelete(Handle<Value> key); 1523 1524 V8EXPORT bool Has(uint32_t index); 1525 1526 V8EXPORT bool Delete(uint32_t index); 1527 1528 V8EXPORT bool SetAccessor(Handle<String> name, 1529 AccessorGetter getter, 1530 AccessorSetter setter = 0, 1531 Handle<Value> data = Handle<Value>(), 1532 AccessControl settings = DEFAULT, 1533 PropertyAttribute attribute = None); 1534 1535 /** 1536 * Returns an array containing the names of the enumerable properties 1537 * of this object, including properties from prototype objects. The 1538 * array returned by this method contains the same values as would 1539 * be enumerated by a for-in statement over this object. 1540 */ 1541 V8EXPORT Local<Array> GetPropertyNames(); 1542 1543 /** 1544 * Get the prototype object. This does not skip objects marked to 1545 * be skipped by __proto__ and it does not consult the security 1546 * handler. 1547 */ 1548 V8EXPORT Local<Value> GetPrototype(); 1549 1550 /** 1551 * Set the prototype object. This does not skip objects marked to 1552 * be skipped by __proto__ and it does not consult the security 1553 * handler. 1554 */ 1555 V8EXPORT bool SetPrototype(Handle<Value> prototype); 1556 1557 /** 1558 * Finds an instance of the given function template in the prototype 1559 * chain. 1560 */ 1561 V8EXPORT Local<Object> FindInstanceInPrototypeChain( 1562 Handle<FunctionTemplate> tmpl); 1563 1564 /** 1565 * Call builtin Object.prototype.toString on this object. 1566 * This is different from Value::ToString() that may call 1567 * user-defined toString function. This one does not. 1568 */ 1569 V8EXPORT Local<String> ObjectProtoToString(); 1570 1571 /** 1572 * Returns the name of the function invoked as a constructor for this object. 1573 */ 1574 V8EXPORT Local<String> GetConstructorName(); 1575 1576 /** Gets the number of internal fields for this Object. */ 1577 V8EXPORT int InternalFieldCount(); 1578 /** Gets the value in an internal field. */ 1579 inline Local<Value> GetInternalField(int index); 1580 /** Sets the value in an internal field. */ 1581 V8EXPORT void SetInternalField(int index, Handle<Value> value); 1582 1583 /** Gets a native pointer from an internal field. */ 1584 inline void* GetPointerFromInternalField(int index); 1585 1586 /** Sets a native pointer in an internal field. */ 1587 V8EXPORT void SetPointerInInternalField(int index, void* value); 1588 1589 // Testers for local properties. 1590 V8EXPORT bool HasRealNamedProperty(Handle<String> key); 1591 V8EXPORT bool HasRealIndexedProperty(uint32_t index); 1592 V8EXPORT bool HasRealNamedCallbackProperty(Handle<String> key); 1593 1594 /** 1595 * If result.IsEmpty() no real property was located in the prototype chain. 1596 * This means interceptors in the prototype chain are not called. 1597 */ 1598 V8EXPORT Local<Value> GetRealNamedPropertyInPrototypeChain( 1599 Handle<String> key); 1600 1601 /** 1602 * If result.IsEmpty() no real property was located on the object or 1603 * in the prototype chain. 1604 * This means interceptors in the prototype chain are not called. 1605 */ 1606 V8EXPORT Local<Value> GetRealNamedProperty(Handle<String> key); 1607 1608 /** Tests for a named lookup interceptor.*/ 1609 V8EXPORT bool HasNamedLookupInterceptor(); 1610 1611 /** Tests for an index lookup interceptor.*/ 1612 V8EXPORT bool HasIndexedLookupInterceptor(); 1613 1614 /** 1615 * Turns on access check on the object if the object is an instance of 1616 * a template that has access check callbacks. If an object has no 1617 * access check info, the object cannot be accessed by anyone. 1618 */ 1619 V8EXPORT void TurnOnAccessCheck(); 1620 1621 /** 1622 * Returns the identity hash for this object. The current implemenation uses 1623 * a hidden property on the object to store the identity hash. 1624 * 1625 * The return value will never be 0. Also, it is not guaranteed to be 1626 * unique. 1627 */ 1628 V8EXPORT int GetIdentityHash(); 1629 1630 /** 1631 * Access hidden properties on JavaScript objects. These properties are 1632 * hidden from the executing JavaScript and only accessible through the V8 1633 * C++ API. Hidden properties introduced by V8 internally (for example the 1634 * identity hash) are prefixed with "v8::". 1635 */ 1636 V8EXPORT bool SetHiddenValue(Handle<String> key, Handle<Value> value); 1637 V8EXPORT Local<Value> GetHiddenValue(Handle<String> key); 1638 V8EXPORT bool DeleteHiddenValue(Handle<String> key); 1639 1640 /** 1641 * Returns true if this is an instance of an api function (one 1642 * created from a function created from a function template) and has 1643 * been modified since it was created. Note that this method is 1644 * conservative and may return true for objects that haven't actually 1645 * been modified. 1646 */ 1647 V8EXPORT bool IsDirty(); 1648 1649 /** 1650 * Clone this object with a fast but shallow copy. Values will point 1651 * to the same values as the original object. 1652 */ 1653 V8EXPORT Local<Object> Clone(); 1654 1655 /** 1656 * Returns the context in which the object was created. 1657 */ 1658 V8EXPORT Local<Context> CreationContext(); 1659 1660 /** 1661 * Set the backing store of the indexed properties to be managed by the 1662 * embedding layer. Access to the indexed properties will follow the rules 1663 * spelled out in CanvasPixelArray. 1664 * Note: The embedding program still owns the data and needs to ensure that 1665 * the backing store is preserved while V8 has a reference. 1666 */ 1667 V8EXPORT void SetIndexedPropertiesToPixelData(uint8_t* data, int length); 1668 V8EXPORT bool HasIndexedPropertiesInPixelData(); 1669 V8EXPORT uint8_t* GetIndexedPropertiesPixelData(); 1670 V8EXPORT int GetIndexedPropertiesPixelDataLength(); 1671 1672 /** 1673 * Set the backing store of the indexed properties to be managed by the 1674 * embedding layer. Access to the indexed properties will follow the rules 1675 * spelled out for the CanvasArray subtypes in the WebGL specification. 1676 * Note: The embedding program still owns the data and needs to ensure that 1677 * the backing store is preserved while V8 has a reference. 1678 */ 1679 V8EXPORT void SetIndexedPropertiesToExternalArrayData( 1680 void* data, 1681 ExternalArrayType array_type, 1682 int number_of_elements); 1683 V8EXPORT bool HasIndexedPropertiesInExternalArrayData(); 1684 V8EXPORT void* GetIndexedPropertiesExternalArrayData(); 1685 V8EXPORT ExternalArrayType GetIndexedPropertiesExternalArrayDataType(); 1686 V8EXPORT int GetIndexedPropertiesExternalArrayDataLength(); 1687 1688 V8EXPORT static Local<Object> New(); 1689 static inline Object* Cast(Value* obj); 1690 private: 1691 V8EXPORT Object(); 1692 V8EXPORT static void CheckCast(Value* obj); 1693 V8EXPORT Local<Value> CheckedGetInternalField(int index); 1694 V8EXPORT void* SlowGetPointerFromInternalField(int index); 1695 1696 /** 1697 * If quick access to the internal field is possible this method 1698 * returns the value. Otherwise an empty handle is returned. 1699 */ 1700 inline Local<Value> UncheckedGetInternalField(int index); 1701 }; 1702 1703 1704 /** 1705 * An instance of the built-in array constructor (ECMA-262, 15.4.2). 1706 */ 1707 class Array : public Object { 1708 public: 1709 V8EXPORT uint32_t Length() const; 1710 1711 /** 1712 * Clones an element at index |index|. Returns an empty 1713 * handle if cloning fails (for any reason). 1714 */ 1715 V8EXPORT Local<Object> CloneElementAt(uint32_t index); 1716 1717 /** 1718 * Creates a JavaScript array with the given length. If the length 1719 * is negative the returned array will have length 0. 1720 */ 1721 V8EXPORT static Local<Array> New(int length = 0); 1722 1723 static inline Array* Cast(Value* obj); 1724 private: 1725 V8EXPORT Array(); 1726 static void CheckCast(Value* obj); 1727 }; 1728 1729 1730 /** 1731 * A JavaScript function object (ECMA-262, 15.3). 1732 */ 1733 class Function : public Object { 1734 public: 1735 V8EXPORT Local<Object> NewInstance() const; 1736 V8EXPORT Local<Object> NewInstance(int argc, Handle<Value> argv[]) const; 1737 V8EXPORT Local<Value> Call(Handle<Object> recv, 1738 int argc, 1739 Handle<Value> argv[]); 1740 V8EXPORT void SetName(Handle<String> name); 1741 V8EXPORT Handle<Value> GetName() const; 1742 1743 /** 1744 * Returns zero based line number of function body and 1745 * kLineOffsetNotFound if no information available. 1746 */ 1747 V8EXPORT int GetScriptLineNumber() const; 1748 V8EXPORT ScriptOrigin GetScriptOrigin() const; 1749 static inline Function* Cast(Value* obj); 1750 V8EXPORT static const int kLineOffsetNotFound; 1751 private: 1752 V8EXPORT Function(); 1753 V8EXPORT static void CheckCast(Value* obj); 1754 }; 1755 1756 1757 /** 1758 * A JavaScript value that wraps a C++ void*. This type of value is 1759 * mainly used to associate C++ data structures with JavaScript 1760 * objects. 1761 * 1762 * The Wrap function V8 will return the most optimal Value object wrapping the 1763 * C++ void*. The type of the value is not guaranteed to be an External object 1764 * and no assumptions about its type should be made. To access the wrapped 1765 * value Unwrap should be used, all other operations on that object will lead 1766 * to unpredictable results. 1767 */ 1768 class External : public Value { 1769 public: 1770 V8EXPORT static Local<Value> Wrap(void* data); 1771 static inline void* Unwrap(Handle<Value> obj); 1772 1773 V8EXPORT static Local<External> New(void* value); 1774 static inline External* Cast(Value* obj); 1775 V8EXPORT void* Value() const; 1776 private: 1777 V8EXPORT External(); 1778 V8EXPORT static void CheckCast(v8::Value* obj); 1779 static inline void* QuickUnwrap(Handle<v8::Value> obj); 1780 V8EXPORT static void* FullUnwrap(Handle<v8::Value> obj); 1781 }; 1782 1783 1784 // --- T e m p l a t e s --- 1785 1786 1787 /** 1788 * The superclass of object and function templates. 1789 */ 1790 class V8EXPORT Template : public Data { 1791 public: 1792 /** Adds a property to each instance created by this template.*/ 1793 void Set(Handle<String> name, Handle<Data> value, 1794 PropertyAttribute attributes = None); 1795 inline void Set(const char* name, Handle<Data> value); 1796 private: 1797 Template(); 1798 1799 friend class ObjectTemplate; 1800 friend class FunctionTemplate; 1801 }; 1802 1803 1804 /** 1805 * The argument information given to function call callbacks. This 1806 * class provides access to information about the context of the call, 1807 * including the receiver, the number and values of arguments, and 1808 * the holder of the function. 1809 */ 1810 class Arguments { 1811 public: 1812 inline int Length() const; 1813 inline Local<Value> operator[](int i) const; 1814 inline Local<Function> Callee() const; 1815 inline Local<Object> This() const; 1816 inline Local<Object> Holder() const; 1817 inline bool IsConstructCall() const; 1818 inline Local<Value> Data() const; 1819 private: 1820 static const int kDataIndex = 0; 1821 static const int kCalleeIndex = -1; 1822 static const int kHolderIndex = -2; 1823 1824 friend class ImplementationUtilities; 1825 inline Arguments(internal::Object** implicit_args, 1826 internal::Object** values, 1827 int length, 1828 bool is_construct_call); 1829 internal::Object** implicit_args_; 1830 internal::Object** values_; 1831 int length_; 1832 bool is_construct_call_; 1833 }; 1834 1835 1836 /** 1837 * The information passed to an accessor callback about the context 1838 * of the property access. 1839 */ 1840 class V8EXPORT AccessorInfo { 1841 public: 1842 inline AccessorInfo(internal::Object** args) 1843 : args_(args) { } 1844 inline Local<Value> Data() const; 1845 inline Local<Object> This() const; 1846 inline Local<Object> Holder() const; 1847 private: 1848 internal::Object** args_; 1849 }; 1850 1851 1852 typedef Handle<Value> (*InvocationCallback)(const Arguments& args); 1853 1854 /** 1855 * NamedProperty[Getter|Setter] are used as interceptors on object. 1856 * See ObjectTemplate::SetNamedPropertyHandler. 1857 */ 1858 typedef Handle<Value> (*NamedPropertyGetter)(Local<String> property, 1859 const AccessorInfo& info); 1860 1861 1862 /** 1863 * Returns the value if the setter intercepts the request. 1864 * Otherwise, returns an empty handle. 1865 */ 1866 typedef Handle<Value> (*NamedPropertySetter)(Local<String> property, 1867 Local<Value> value, 1868 const AccessorInfo& info); 1869 1870 /** 1871 * Returns a non-empty handle if the interceptor intercepts the request. 1872 * The result is an integer encoding property attributes (like v8::None, 1873 * v8::DontEnum, etc.) 1874 */ 1875 typedef Handle<Integer> (*NamedPropertyQuery)(Local<String> property, 1876 const AccessorInfo& info); 1877 1878 1879 /** 1880 * Returns a non-empty handle if the deleter intercepts the request. 1881 * The return value is true if the property could be deleted and false 1882 * otherwise. 1883 */ 1884 typedef Handle<Boolean> (*NamedPropertyDeleter)(Local<String> property, 1885 const AccessorInfo& info); 1886 1887 /** 1888 * Returns an array containing the names of the properties the named 1889 * property getter intercepts. 1890 */ 1891 typedef Handle<Array> (*NamedPropertyEnumerator)(const AccessorInfo& info); 1892 1893 1894 /** 1895 * Returns the value of the property if the getter intercepts the 1896 * request. Otherwise, returns an empty handle. 1897 */ 1898 typedef Handle<Value> (*IndexedPropertyGetter)(uint32_t index, 1899 const AccessorInfo& info); 1900 1901 1902 /** 1903 * Returns the value if the setter intercepts the request. 1904 * Otherwise, returns an empty handle. 1905 */ 1906 typedef Handle<Value> (*IndexedPropertySetter)(uint32_t index, 1907 Local<Value> value, 1908 const AccessorInfo& info); 1909 1910 1911 /** 1912 * Returns a non-empty handle if the interceptor intercepts the request. 1913 * The result is an integer encoding property attributes. 1914 */ 1915 typedef Handle<Integer> (*IndexedPropertyQuery)(uint32_t index, 1916 const AccessorInfo& info); 1917 1918 /** 1919 * Returns a non-empty handle if the deleter intercepts the request. 1920 * The return value is true if the property could be deleted and false 1921 * otherwise. 1922 */ 1923 typedef Handle<Boolean> (*IndexedPropertyDeleter)(uint32_t index, 1924 const AccessorInfo& info); 1925 1926 /** 1927 * Returns an array containing the indices of the properties the 1928 * indexed property getter intercepts. 1929 */ 1930 typedef Handle<Array> (*IndexedPropertyEnumerator)(const AccessorInfo& info); 1931 1932 1933 /** 1934 * Access type specification. 1935 */ 1936 enum AccessType { 1937 ACCESS_GET, 1938 ACCESS_SET, 1939 ACCESS_HAS, 1940 ACCESS_DELETE, 1941 ACCESS_KEYS 1942 }; 1943 1944 1945 /** 1946 * Returns true if cross-context access should be allowed to the named 1947 * property with the given key on the host object. 1948 */ 1949 typedef bool (*NamedSecurityCallback)(Local<Object> host, 1950 Local<Value> key, 1951 AccessType type, 1952 Local<Value> data); 1953 1954 1955 /** 1956 * Returns true if cross-context access should be allowed to the indexed 1957 * property with the given index on the host object. 1958 */ 1959 typedef bool (*IndexedSecurityCallback)(Local<Object> host, 1960 uint32_t index, 1961 AccessType type, 1962 Local<Value> data); 1963 1964 1965 /** 1966 * A FunctionTemplate is used to create functions at runtime. There 1967 * can only be one function created from a FunctionTemplate in a 1968 * context. The lifetime of the created function is equal to the 1969 * lifetime of the context. So in case the embedder needs to create 1970 * temporary functions that can be collected using Scripts is 1971 * preferred. 1972 * 1973 * A FunctionTemplate can have properties, these properties are added to the 1974 * function object when it is created. 1975 * 1976 * A FunctionTemplate has a corresponding instance template which is 1977 * used to create object instances when the function is used as a 1978 * constructor. Properties added to the instance template are added to 1979 * each object instance. 1980 * 1981 * A FunctionTemplate can have a prototype template. The prototype template 1982 * is used to create the prototype object of the function. 1983 * 1984 * The following example shows how to use a FunctionTemplate: 1985 * 1986 * \code 1987 * v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(); 1988 * t->Set("func_property", v8::Number::New(1)); 1989 * 1990 * v8::Local<v8::Template> proto_t = t->PrototypeTemplate(); 1991 * proto_t->Set("proto_method", v8::FunctionTemplate::New(InvokeCallback)); 1992 * proto_t->Set("proto_const", v8::Number::New(2)); 1993 * 1994 * v8::Local<v8::ObjectTemplate> instance_t = t->InstanceTemplate(); 1995 * instance_t->SetAccessor("instance_accessor", InstanceAccessorCallback); 1996 * instance_t->SetNamedPropertyHandler(PropertyHandlerCallback, ...); 1997 * instance_t->Set("instance_property", Number::New(3)); 1998 * 1999 * v8::Local<v8::Function> function = t->GetFunction(); 2000 * v8::Local<v8::Object> instance = function->NewInstance(); 2001 * \endcode 2002 * 2003 * Let's use "function" as the JS variable name of the function object 2004 * and "instance" for the instance object created above. The function 2005 * and the instance will have the following properties: 2006 * 2007 * \code 2008 * func_property in function == true; 2009 * function.func_property == 1; 2010 * 2011 * function.prototype.proto_method() invokes 'InvokeCallback' 2012 * function.prototype.proto_const == 2; 2013 * 2014 * instance instanceof function == true; 2015 * instance.instance_accessor calls 'InstanceAccessorCallback' 2016 * instance.instance_property == 3; 2017 * \endcode 2018 * 2019 * A FunctionTemplate can inherit from another one by calling the 2020 * FunctionTemplate::Inherit method. The following graph illustrates 2021 * the semantics of inheritance: 2022 * 2023 * \code 2024 * FunctionTemplate Parent -> Parent() . prototype -> { } 2025 * ^ ^ 2026 * | Inherit(Parent) | .__proto__ 2027 * | | 2028 * FunctionTemplate Child -> Child() . prototype -> { } 2029 * \endcode 2030 * 2031 * A FunctionTemplate 'Child' inherits from 'Parent', the prototype 2032 * object of the Child() function has __proto__ pointing to the 2033 * Parent() function's prototype object. An instance of the Child 2034 * function has all properties on Parent's instance templates. 2035 * 2036 * Let Parent be the FunctionTemplate initialized in the previous 2037 * section and create a Child FunctionTemplate by: 2038 * 2039 * \code 2040 * Local<FunctionTemplate> parent = t; 2041 * Local<FunctionTemplate> child = FunctionTemplate::New(); 2042 * child->Inherit(parent); 2043 * 2044 * Local<Function> child_function = child->GetFunction(); 2045 * Local<Object> child_instance = child_function->NewInstance(); 2046 * \endcode 2047 * 2048 * The Child function and Child instance will have the following 2049 * properties: 2050 * 2051 * \code 2052 * child_func.prototype.__proto__ == function.prototype; 2053 * child_instance.instance_accessor calls 'InstanceAccessorCallback' 2054 * child_instance.instance_property == 3; 2055 * \endcode 2056 */ 2057 class V8EXPORT FunctionTemplate : public Template { 2058 public: 2059 /** Creates a function template.*/ 2060 static Local<FunctionTemplate> New( 2061 InvocationCallback callback = 0, 2062 Handle<Value> data = Handle<Value>(), 2063 Handle<Signature> signature = Handle<Signature>()); 2064 /** Returns the unique function instance in the current execution context.*/ 2065 Local<Function> GetFunction(); 2066 2067 /** 2068 * Set the call-handler callback for a FunctionTemplate. This 2069 * callback is called whenever the function created from this 2070 * FunctionTemplate is called. 2071 */ 2072 void SetCallHandler(InvocationCallback callback, 2073 Handle<Value> data = Handle<Value>()); 2074 2075 /** Get the InstanceTemplate. */ 2076 Local<ObjectTemplate> InstanceTemplate(); 2077 2078 /** Causes the function template to inherit from a parent function template.*/ 2079 void Inherit(Handle<FunctionTemplate> parent); 2080 2081 /** 2082 * A PrototypeTemplate is the template used to create the prototype object 2083 * of the function created by this template. 2084 */ 2085 Local<ObjectTemplate> PrototypeTemplate(); 2086 2087 2088 /** 2089 * Set the class name of the FunctionTemplate. This is used for 2090 * printing objects created with the function created from the 2091 * FunctionTemplate as its constructor. 2092 */ 2093 void SetClassName(Handle<String> name); 2094 2095 /** 2096 * Determines whether the __proto__ accessor ignores instances of 2097 * the function template. If instances of the function template are 2098 * ignored, __proto__ skips all instances and instead returns the 2099 * next object in the prototype chain. 2100 * 2101 * Call with a value of true to make the __proto__ accessor ignore 2102 * instances of the function template. Call with a value of false 2103 * to make the __proto__ accessor not ignore instances of the 2104 * function template. By default, instances of a function template 2105 * are not ignored. 2106 */ 2107 void SetHiddenPrototype(bool value); 2108 2109 /** 2110 * Returns true if the given object is an instance of this function 2111 * template. 2112 */ 2113 bool HasInstance(Handle<Value> object); 2114 2115 private: 2116 FunctionTemplate(); 2117 void AddInstancePropertyAccessor(Handle<String> name, 2118 AccessorGetter getter, 2119 AccessorSetter setter, 2120 Handle<Value> data, 2121 AccessControl settings, 2122 PropertyAttribute attributes); 2123 void SetNamedInstancePropertyHandler(NamedPropertyGetter getter, 2124 NamedPropertySetter setter, 2125 NamedPropertyQuery query, 2126 NamedPropertyDeleter remover, 2127 NamedPropertyEnumerator enumerator, 2128 Handle<Value> data); 2129 void SetIndexedInstancePropertyHandler(IndexedPropertyGetter getter, 2130 IndexedPropertySetter setter, 2131 IndexedPropertyQuery query, 2132 IndexedPropertyDeleter remover, 2133 IndexedPropertyEnumerator enumerator, 2134 Handle<Value> data); 2135 void SetInstanceCallAsFunctionHandler(InvocationCallback callback, 2136 Handle<Value> data); 2137 2138 friend class Context; 2139 friend class ObjectTemplate; 2140 }; 2141 2142 2143 /** 2144 * An ObjectTemplate is used to create objects at runtime. 2145 * 2146 * Properties added to an ObjectTemplate are added to each object 2147 * created from the ObjectTemplate. 2148 */ 2149 class V8EXPORT ObjectTemplate : public Template { 2150 public: 2151 /** Creates an ObjectTemplate. */ 2152 static Local<ObjectTemplate> New(); 2153 2154 /** Creates a new instance of this template.*/ 2155 Local<Object> NewInstance(); 2156 2157 /** 2158 * Sets an accessor on the object template. 2159 * 2160 * Whenever the property with the given name is accessed on objects 2161 * created from this ObjectTemplate the getter and setter callbacks 2162 * are called instead of getting and setting the property directly 2163 * on the JavaScript object. 2164 * 2165 * \param name The name of the property for which an accessor is added. 2166 * \param getter The callback to invoke when getting the property. 2167 * \param setter The callback to invoke when setting the property. 2168 * \param data A piece of data that will be passed to the getter and setter 2169 * callbacks whenever they are invoked. 2170 * \param settings Access control settings for the accessor. This is a bit 2171 * field consisting of one of more of 2172 * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2. 2173 * The default is to not allow cross-context access. 2174 * ALL_CAN_READ means that all cross-context reads are allowed. 2175 * ALL_CAN_WRITE means that all cross-context writes are allowed. 2176 * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all 2177 * cross-context access. 2178 * \param attribute The attributes of the property for which an accessor 2179 * is added. 2180 */ 2181 void SetAccessor(Handle<String> name, 2182 AccessorGetter getter, 2183 AccessorSetter setter = 0, 2184 Handle<Value> data = Handle<Value>(), 2185 AccessControl settings = DEFAULT, 2186 PropertyAttribute attribute = None); 2187 2188 /** 2189 * Sets a named property handler on the object template. 2190 * 2191 * Whenever a named property is accessed on objects created from 2192 * this object template, the provided callback is invoked instead of 2193 * accessing the property directly on the JavaScript object. 2194 * 2195 * \param getter The callback to invoke when getting a property. 2196 * \param setter The callback to invoke when setting a property. 2197 * \param query The callback to invoke to check if a property is present, 2198 * and if present, get its attributes. 2199 * \param deleter The callback to invoke when deleting a property. 2200 * \param enumerator The callback to invoke to enumerate all the named 2201 * properties of an object. 2202 * \param data A piece of data that will be passed to the callbacks 2203 * whenever they are invoked. 2204 */ 2205 void SetNamedPropertyHandler(NamedPropertyGetter getter, 2206 NamedPropertySetter setter = 0, 2207 NamedPropertyQuery query = 0, 2208 NamedPropertyDeleter deleter = 0, 2209 NamedPropertyEnumerator enumerator = 0, 2210 Handle<Value> data = Handle<Value>()); 2211 2212 /** 2213 * Sets an indexed property handler on the object template. 2214 * 2215 * Whenever an indexed property is accessed on objects created from 2216 * this object template, the provided callback is invoked instead of 2217 * accessing the property directly on the JavaScript object. 2218 * 2219 * \param getter The callback to invoke when getting a property. 2220 * \param setter The callback to invoke when setting a property. 2221 * \param query The callback to invoke to check is an object has a property. 2222 * \param deleter The callback to invoke when deleting a property. 2223 * \param enumerator The callback to invoke to enumerate all the indexed 2224 * properties of an object. 2225 * \param data A piece of data that will be passed to the callbacks 2226 * whenever they are invoked. 2227 */ 2228 void SetIndexedPropertyHandler(IndexedPropertyGetter getter, 2229 IndexedPropertySetter setter = 0, 2230 IndexedPropertyQuery query = 0, 2231 IndexedPropertyDeleter deleter = 0, 2232 IndexedPropertyEnumerator enumerator = 0, 2233 Handle<Value> data = Handle<Value>()); 2234 2235 /** 2236 * Sets the callback to be used when calling instances created from 2237 * this template as a function. If no callback is set, instances 2238 * behave like normal JavaScript objects that cannot be called as a 2239 * function. 2240 */ 2241 void SetCallAsFunctionHandler(InvocationCallback callback, 2242 Handle<Value> data = Handle<Value>()); 2243 2244 /** 2245 * Mark object instances of the template as undetectable. 2246 * 2247 * In many ways, undetectable objects behave as though they are not 2248 * there. They behave like 'undefined' in conditionals and when 2249 * printed. However, properties can be accessed and called as on 2250 * normal objects. 2251 */ 2252 void MarkAsUndetectable(); 2253 2254 /** 2255 * Sets access check callbacks on the object template. 2256 * 2257 * When accessing properties on instances of this object template, 2258 * the access check callback will be called to determine whether or 2259 * not to allow cross-context access to the properties. 2260 * The last parameter specifies whether access checks are turned 2261 * on by default on instances. If access checks are off by default, 2262 * they can be turned on on individual instances by calling 2263 * Object::TurnOnAccessCheck(). 2264 */ 2265 void SetAccessCheckCallbacks(NamedSecurityCallback named_handler, 2266 IndexedSecurityCallback indexed_handler, 2267 Handle<Value> data = Handle<Value>(), 2268 bool turned_on_by_default = true); 2269 2270 /** 2271 * Gets the number of internal fields for objects generated from 2272 * this template. 2273 */ 2274 int InternalFieldCount(); 2275 2276 /** 2277 * Sets the number of internal fields for objects generated from 2278 * this template. 2279 */ 2280 void SetInternalFieldCount(int value); 2281 2282 private: 2283 ObjectTemplate(); 2284 static Local<ObjectTemplate> New(Handle<FunctionTemplate> constructor); 2285 friend class FunctionTemplate; 2286 }; 2287 2288 2289 /** 2290 * A Signature specifies which receivers and arguments a function can 2291 * legally be called with. 2292 */ 2293 class V8EXPORT Signature : public Data { 2294 public: 2295 static Local<Signature> New(Handle<FunctionTemplate> receiver = 2296 Handle<FunctionTemplate>(), 2297 int argc = 0, 2298 Handle<FunctionTemplate> argv[] = 0); 2299 private: 2300 Signature(); 2301 }; 2302 2303 2304 /** 2305 * A utility for determining the type of objects based on the template 2306 * they were constructed from. 2307 */ 2308 class V8EXPORT TypeSwitch : public Data { 2309 public: 2310 static Local<TypeSwitch> New(Handle<FunctionTemplate> type); 2311 static Local<TypeSwitch> New(int argc, Handle<FunctionTemplate> types[]); 2312 int match(Handle<Value> value); 2313 private: 2314 TypeSwitch(); 2315 }; 2316 2317 2318 // --- E x t e n s i o n s --- 2319 2320 2321 /** 2322 * Ignore 2323 */ 2324 class V8EXPORT Extension { // NOLINT 2325 public: 2326 Extension(const char* name, 2327 const char* source = 0, 2328 int dep_count = 0, 2329 const char** deps = 0); 2330 virtual ~Extension() { } 2331 virtual v8::Handle<v8::FunctionTemplate> 2332 GetNativeFunction(v8::Handle<v8::String> name) { 2333 return v8::Handle<v8::FunctionTemplate>(); 2334 } 2335 2336 const char* name() { return name_; } 2337 const char* source() { return source_; } 2338 int dependency_count() { return dep_count_; } 2339 const char** dependencies() { return deps_; } 2340 void set_auto_enable(bool value) { auto_enable_ = value; } 2341 bool auto_enable() { return auto_enable_; } 2342 2343 private: 2344 const char* name_; 2345 const char* source_; 2346 int dep_count_; 2347 const char** deps_; 2348 bool auto_enable_; 2349 2350 // Disallow copying and assigning. 2351 Extension(const Extension&); 2352 void operator=(const Extension&); 2353 }; 2354 2355 2356 void V8EXPORT RegisterExtension(Extension* extension); 2357 2358 2359 /** 2360 * Ignore 2361 */ 2362 class V8EXPORT DeclareExtension { 2363 public: 2364 inline DeclareExtension(Extension* extension) { 2365 RegisterExtension(extension); 2366 } 2367 }; 2368 2369 2370 // --- S t a t i c s --- 2371 2372 2373 Handle<Primitive> V8EXPORT Undefined(); 2374 Handle<Primitive> V8EXPORT Null(); 2375 Handle<Boolean> V8EXPORT True(); 2376 Handle<Boolean> V8EXPORT False(); 2377 2378 2379 /** 2380 * A set of constraints that specifies the limits of the runtime's memory use. 2381 * You must set the heap size before initializing the VM - the size cannot be 2382 * adjusted after the VM is initialized. 2383 * 2384 * If you are using threads then you should hold the V8::Locker lock while 2385 * setting the stack limit and you must set a non-default stack limit separately 2386 * for each thread. 2387 */ 2388 class V8EXPORT ResourceConstraints { 2389 public: 2390 ResourceConstraints(); 2391 int max_young_space_size() const { return max_young_space_size_; } 2392 void set_max_young_space_size(int value) { max_young_space_size_ = value; } 2393 int max_old_space_size() const { return max_old_space_size_; } 2394 void set_max_old_space_size(int value) { max_old_space_size_ = value; } 2395 int max_executable_size() { return max_executable_size_; } 2396 void set_max_executable_size(int value) { max_executable_size_ = value; } 2397 uint32_t* stack_limit() const { return stack_limit_; } 2398 // Sets an address beyond which the VM's stack may not grow. 2399 void set_stack_limit(uint32_t* value) { stack_limit_ = value; } 2400 private: 2401 int max_young_space_size_; 2402 int max_old_space_size_; 2403 int max_executable_size_; 2404 uint32_t* stack_limit_; 2405 }; 2406 2407 2408 bool V8EXPORT SetResourceConstraints(ResourceConstraints* constraints); 2409 2410 2411 // --- E x c e p t i o n s --- 2412 2413 2414 typedef void (*FatalErrorCallback)(const char* location, const char* message); 2415 2416 2417 typedef void (*MessageCallback)(Handle<Message> message, Handle<Value> data); 2418 2419 2420 /** 2421 * Schedules an exception to be thrown when returning to JavaScript. When an 2422 * exception has been scheduled it is illegal to invoke any JavaScript 2423 * operation; the caller must return immediately and only after the exception 2424 * has been handled does it become legal to invoke JavaScript operations. 2425 */ 2426 Handle<Value> V8EXPORT ThrowException(Handle<Value> exception); 2427 2428 /** 2429 * Create new error objects by calling the corresponding error object 2430 * constructor with the message. 2431 */ 2432 class V8EXPORT Exception { 2433 public: 2434 static Local<Value> RangeError(Handle<String> message); 2435 static Local<Value> ReferenceError(Handle<String> message); 2436 static Local<Value> SyntaxError(Handle<String> message); 2437 static Local<Value> TypeError(Handle<String> message); 2438 static Local<Value> Error(Handle<String> message); 2439 }; 2440 2441 2442 // --- C o u n t e r s C a l l b a c k s --- 2443 2444 typedef int* (*CounterLookupCallback)(const char* name); 2445 2446 typedef void* (*CreateHistogramCallback)(const char* name, 2447 int min, 2448 int max, 2449 size_t buckets); 2450 2451 typedef void (*AddHistogramSampleCallback)(void* histogram, int sample); 2452 2453 // --- M e m o r y A l l o c a t i o n C a l l b a c k --- 2454 enum ObjectSpace { 2455 kObjectSpaceNewSpace = 1 << 0, 2456 kObjectSpaceOldPointerSpace = 1 << 1, 2457 kObjectSpaceOldDataSpace = 1 << 2, 2458 kObjectSpaceCodeSpace = 1 << 3, 2459 kObjectSpaceMapSpace = 1 << 4, 2460 kObjectSpaceLoSpace = 1 << 5, 2461 2462 kObjectSpaceAll = kObjectSpaceNewSpace | kObjectSpaceOldPointerSpace | 2463 kObjectSpaceOldDataSpace | kObjectSpaceCodeSpace | kObjectSpaceMapSpace | 2464 kObjectSpaceLoSpace 2465 }; 2466 2467 enum AllocationAction { 2468 kAllocationActionAllocate = 1 << 0, 2469 kAllocationActionFree = 1 << 1, 2470 kAllocationActionAll = kAllocationActionAllocate | kAllocationActionFree 2471 }; 2472 2473 typedef void (*MemoryAllocationCallback)(ObjectSpace space, 2474 AllocationAction action, 2475 int size); 2476 2477 // --- F a i l e d A c c e s s C h e c k C a l l b a c k --- 2478 typedef void (*FailedAccessCheckCallback)(Local<Object> target, 2479 AccessType type, 2480 Local<Value> data); 2481 2482 // --- G a r b a g e C o l l e c t i o n C a l l b a c k s 2483 2484 /** 2485 * Applications can register callback functions which will be called 2486 * before and after a garbage collection. Allocations are not 2487 * allowed in the callback functions, you therefore cannot manipulate 2488 * objects (set or delete properties for example) since it is possible 2489 * such operations will result in the allocation of objects. 2490 */ 2491 enum GCType { 2492 kGCTypeScavenge = 1 << 0, 2493 kGCTypeMarkSweepCompact = 1 << 1, 2494 kGCTypeAll = kGCTypeScavenge | kGCTypeMarkSweepCompact 2495 }; 2496 2497 enum GCCallbackFlags { 2498 kNoGCCallbackFlags = 0, 2499 kGCCallbackFlagCompacted = 1 << 0 2500 }; 2501 2502 typedef void (*GCPrologueCallback)(GCType type, GCCallbackFlags flags); 2503 typedef void (*GCEpilogueCallback)(GCType type, GCCallbackFlags flags); 2504 2505 typedef void (*GCCallback)(); 2506 2507 2508 /** 2509 * Profiler modules. 2510 * 2511 * In V8, profiler consists of several modules: CPU profiler, and different 2512 * kinds of heap profiling. Each can be turned on / off independently. 2513 * When PROFILER_MODULE_HEAP_SNAPSHOT flag is passed to ResumeProfilerEx, 2514 * modules are enabled only temporarily for making a snapshot of the heap. 2515 */ 2516 enum ProfilerModules { 2517 PROFILER_MODULE_NONE = 0, 2518 PROFILER_MODULE_CPU = 1, 2519 PROFILER_MODULE_HEAP_STATS = 1 << 1, 2520 PROFILER_MODULE_JS_CONSTRUCTORS = 1 << 2, 2521 PROFILER_MODULE_HEAP_SNAPSHOT = 1 << 16 2522 }; 2523 2524 2525 /** 2526 * Collection of V8 heap information. 2527 * 2528 * Instances of this class can be passed to v8::V8::HeapStatistics to 2529 * get heap statistics from V8. 2530 */ 2531 class V8EXPORT HeapStatistics { 2532 public: 2533 HeapStatistics(); 2534 size_t total_heap_size() { return total_heap_size_; } 2535 size_t total_heap_size_executable() { return total_heap_size_executable_; } 2536 size_t used_heap_size() { return used_heap_size_; } 2537 size_t heap_size_limit() { return heap_size_limit_; } 2538 2539 private: 2540 void set_total_heap_size(size_t size) { total_heap_size_ = size; } 2541 void set_total_heap_size_executable(size_t size) { 2542 total_heap_size_executable_ = size; 2543 } 2544 void set_used_heap_size(size_t size) { used_heap_size_ = size; } 2545 void set_heap_size_limit(size_t size) { heap_size_limit_ = size; } 2546 2547 size_t total_heap_size_; 2548 size_t total_heap_size_executable_; 2549 size_t used_heap_size_; 2550 size_t heap_size_limit_; 2551 2552 friend class V8; 2553 }; 2554 2555 2556 class RetainedObjectInfo; 2557 2558 /** 2559 * Isolate represents an isolated instance of the V8 engine. V8 2560 * isolates have completely separate states. Objects from one isolate 2561 * must not be used in other isolates. When V8 is initialized a 2562 * default isolate is implicitly created and entered. The embedder 2563 * can create additional isolates and use them in parallel in multiple 2564 * threads. An isolate can be entered by at most one thread at any 2565 * given time. The Locker/Unlocker API can be used to synchronize. 2566 */ 2567 class V8EXPORT Isolate { 2568 public: 2569 /** 2570 * Stack-allocated class which sets the isolate for all operations 2571 * executed within a local scope. 2572 */ 2573 class V8EXPORT Scope { 2574 public: 2575 explicit Scope(Isolate* isolate) : isolate_(isolate) { 2576 isolate->Enter(); 2577 } 2578 2579 ~Scope() { isolate_->Exit(); } 2580 2581 private: 2582 Isolate* const isolate_; 2583 2584 // Prevent copying of Scope objects. 2585 Scope(const Scope&); 2586 Scope& operator=(const Scope&); 2587 }; 2588 2589 /** 2590 * Creates a new isolate. Does not change the currently entered 2591 * isolate. 2592 * 2593 * When an isolate is no longer used its resources should be freed 2594 * by calling Dispose(). Using the delete operator is not allowed. 2595 */ 2596 static Isolate* New(); 2597 2598 /** 2599 * Returns the entered isolate for the current thread or NULL in 2600 * case there is no current isolate. 2601 */ 2602 static Isolate* GetCurrent(); 2603 2604 /** 2605 * Methods below this point require holding a lock (using Locker) in 2606 * a multi-threaded environment. 2607 */ 2608 2609 /** 2610 * Sets this isolate as the entered one for the current thread. 2611 * Saves the previously entered one (if any), so that it can be 2612 * restored when exiting. Re-entering an isolate is allowed. 2613 */ 2614 void Enter(); 2615 2616 /** 2617 * Exits this isolate by restoring the previously entered one in the 2618 * current thread. The isolate may still stay the same, if it was 2619 * entered more than once. 2620 * 2621 * Requires: this == Isolate::GetCurrent(). 2622 */ 2623 void Exit(); 2624 2625 /** 2626 * Disposes the isolate. The isolate must not be entered by any 2627 * thread to be disposable. 2628 */ 2629 void Dispose(); 2630 2631 private: 2632 2633 Isolate(); 2634 Isolate(const Isolate&); 2635 ~Isolate(); 2636 Isolate& operator=(const Isolate&); 2637 void* operator new(size_t size); 2638 void operator delete(void*, size_t); 2639 }; 2640 2641 2642 /** 2643 * Container class for static utility functions. 2644 */ 2645 class V8EXPORT V8 { 2646 public: 2647 /** Set the callback to invoke in case of fatal errors. */ 2648 static void SetFatalErrorHandler(FatalErrorCallback that); 2649 2650 /** 2651 * Ignore out-of-memory exceptions. 2652 * 2653 * V8 running out of memory is treated as a fatal error by default. 2654 * This means that the fatal error handler is called and that V8 is 2655 * terminated. 2656 * 2657 * IgnoreOutOfMemoryException can be used to not treat a 2658 * out-of-memory situation as a fatal error. This way, the contexts 2659 * that did not cause the out of memory problem might be able to 2660 * continue execution. 2661 */ 2662 static void IgnoreOutOfMemoryException(); 2663 2664 /** 2665 * Check if V8 is dead and therefore unusable. This is the case after 2666 * fatal errors such as out-of-memory situations. 2667 */ 2668 static bool IsDead(); 2669 2670 /** 2671 * Adds a message listener. 2672 * 2673 * The same message listener can be added more than once and it that 2674 * case it will be called more than once for each message. 2675 */ 2676 static bool AddMessageListener(MessageCallback that, 2677 Handle<Value> data = Handle<Value>()); 2678 2679 /** 2680 * Remove all message listeners from the specified callback function. 2681 */ 2682 static void RemoveMessageListeners(MessageCallback that); 2683 2684 /** 2685 * Tells V8 to capture current stack trace when uncaught exception occurs 2686 * and report it to the message listeners. The option is off by default. 2687 */ 2688 static void SetCaptureStackTraceForUncaughtExceptions( 2689 bool capture, 2690 int frame_limit = 10, 2691 StackTrace::StackTraceOptions options = StackTrace::kOverview); 2692 2693 /** 2694 * Sets V8 flags from a string. 2695 */ 2696 static void SetFlagsFromString(const char* str, int length); 2697 2698 /** 2699 * Sets V8 flags from the command line. 2700 */ 2701 static void SetFlagsFromCommandLine(int* argc, 2702 char** argv, 2703 bool remove_flags); 2704 2705 /** Get the version string. */ 2706 static const char* GetVersion(); 2707 2708 /** 2709 * Enables the host application to provide a mechanism for recording 2710 * statistics counters. 2711 */ 2712 static void SetCounterFunction(CounterLookupCallback); 2713 2714 /** 2715 * Enables the host application to provide a mechanism for recording 2716 * histograms. The CreateHistogram function returns a 2717 * histogram which will later be passed to the AddHistogramSample 2718 * function. 2719 */ 2720 static void SetCreateHistogramFunction(CreateHistogramCallback); 2721 static void SetAddHistogramSampleFunction(AddHistogramSampleCallback); 2722 2723 /** 2724 * Enables the computation of a sliding window of states. The sliding 2725 * window information is recorded in statistics counters. 2726 */ 2727 static void EnableSlidingStateWindow(); 2728 2729 /** Callback function for reporting failed access checks.*/ 2730 static void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback); 2731 2732 /** 2733 * Enables the host application to receive a notification before a 2734 * garbage collection. Allocations are not allowed in the 2735 * callback function, you therefore cannot manipulate objects (set 2736 * or delete properties for example) since it is possible such 2737 * operations will result in the allocation of objects. It is possible 2738 * to specify the GCType filter for your callback. But it is not possible to 2739 * register the same callback function two times with different 2740 * GCType filters. 2741 */ 2742 static void AddGCPrologueCallback( 2743 GCPrologueCallback callback, GCType gc_type_filter = kGCTypeAll); 2744 2745 /** 2746 * This function removes callback which was installed by 2747 * AddGCPrologueCallback function. 2748 */ 2749 static void RemoveGCPrologueCallback(GCPrologueCallback callback); 2750 2751 /** 2752 * The function is deprecated. Please use AddGCPrologueCallback instead. 2753 * Enables the host application to receive a notification before a 2754 * garbage collection. Allocations are not allowed in the 2755 * callback function, you therefore cannot manipulate objects (set 2756 * or delete properties for example) since it is possible such 2757 * operations will result in the allocation of objects. 2758 */ 2759 static void SetGlobalGCPrologueCallback(GCCallback); 2760 2761 /** 2762 * Enables the host application to receive a notification after a 2763 * garbage collection. Allocations are not allowed in the 2764 * callback function, you therefore cannot manipulate objects (set 2765 * or delete properties for example) since it is possible such 2766 * operations will result in the allocation of objects. It is possible 2767 * to specify the GCType filter for your callback. But it is not possible to 2768 * register the same callback function two times with different 2769 * GCType filters. 2770 */ 2771 static void AddGCEpilogueCallback( 2772 GCEpilogueCallback callback, GCType gc_type_filter = kGCTypeAll); 2773 2774 /** 2775 * This function removes callback which was installed by 2776 * AddGCEpilogueCallback function. 2777 */ 2778 static void RemoveGCEpilogueCallback(GCEpilogueCallback callback); 2779 2780 /** 2781 * The function is deprecated. Please use AddGCEpilogueCallback instead. 2782 * Enables the host application to receive a notification after a 2783 * major garbage collection. Allocations are not allowed in the 2784 * callback function, you therefore cannot manipulate objects (set 2785 * or delete properties for example) since it is possible such 2786 * operations will result in the allocation of objects. 2787 */ 2788 static void SetGlobalGCEpilogueCallback(GCCallback); 2789 2790 /** 2791 * Enables the host application to provide a mechanism to be notified 2792 * and perform custom logging when V8 Allocates Executable Memory. 2793 */ 2794 static void AddMemoryAllocationCallback(MemoryAllocationCallback callback, 2795 ObjectSpace space, 2796 AllocationAction action); 2797 2798 /** 2799 * This function removes callback which was installed by 2800 * AddMemoryAllocationCallback function. 2801 */ 2802 static void RemoveMemoryAllocationCallback(MemoryAllocationCallback callback); 2803 2804 /** 2805 * Allows the host application to group objects together. If one 2806 * object in the group is alive, all objects in the group are alive. 2807 * After each garbage collection, object groups are removed. It is 2808 * intended to be used in the before-garbage-collection callback 2809 * function, for instance to simulate DOM tree connections among JS 2810 * wrapper objects. 2811 * See v8-profiler.h for RetainedObjectInfo interface description. 2812 */ 2813 static void AddObjectGroup(Persistent<Value>* objects, 2814 size_t length, 2815 RetainedObjectInfo* info = NULL); 2816 2817 /** 2818 * Allows the host application to declare implicit references between 2819 * the objects: if |parent| is alive, all |children| are alive too. 2820 * After each garbage collection, all implicit references 2821 * are removed. It is intended to be used in the before-garbage-collection 2822 * callback function. 2823 */ 2824 static void AddImplicitReferences(Persistent<Object> parent, 2825 Persistent<Value>* children, 2826 size_t length); 2827 2828 /** 2829 * Initializes from snapshot if possible. Otherwise, attempts to 2830 * initialize from scratch. This function is called implicitly if 2831 * you use the API without calling it first. 2832 */ 2833 static bool Initialize(); 2834 2835 /** 2836 * Adjusts the amount of registered external memory. Used to give 2837 * V8 an indication of the amount of externally allocated memory 2838 * that is kept alive by JavaScript objects. V8 uses this to decide 2839 * when to perform global garbage collections. Registering 2840 * externally allocated memory will trigger global garbage 2841 * collections more often than otherwise in an attempt to garbage 2842 * collect the JavaScript objects keeping the externally allocated 2843 * memory alive. 2844 * 2845 * \param change_in_bytes the change in externally allocated memory 2846 * that is kept alive by JavaScript objects. 2847 * \returns the adjusted value. 2848 */ 2849 static int AdjustAmountOfExternalAllocatedMemory(int change_in_bytes); 2850 2851 /** 2852 * Suspends recording of tick samples in the profiler. 2853 * When the V8 profiling mode is enabled (usually via command line 2854 * switches) this function suspends recording of tick samples. 2855 * Profiling ticks are discarded until ResumeProfiler() is called. 2856 * 2857 * See also the --prof and --prof_auto command line switches to 2858 * enable V8 profiling. 2859 */ 2860 static void PauseProfiler(); 2861 2862 /** 2863 * Resumes recording of tick samples in the profiler. 2864 * See also PauseProfiler(). 2865 */ 2866 static void ResumeProfiler(); 2867 2868 /** 2869 * Return whether profiler is currently paused. 2870 */ 2871 static bool IsProfilerPaused(); 2872 2873 /** 2874 * Resumes specified profiler modules. Can be called several times to 2875 * mark the opening of a profiler events block with the given tag. 2876 * 2877 * "ResumeProfiler" is equivalent to "ResumeProfilerEx(PROFILER_MODULE_CPU)". 2878 * See ProfilerModules enum. 2879 * 2880 * \param flags Flags specifying profiler modules. 2881 * \param tag Profile tag. 2882 */ 2883 static void ResumeProfilerEx(int flags, int tag = 0); 2884 2885 /** 2886 * Pauses specified profiler modules. Each call to "PauseProfilerEx" closes 2887 * a block of profiler events opened by a call to "ResumeProfilerEx" with the 2888 * same tag value. There is no need for blocks to be properly nested. 2889 * The profiler is paused when the last opened block is closed. 2890 * 2891 * "PauseProfiler" is equivalent to "PauseProfilerEx(PROFILER_MODULE_CPU)". 2892 * See ProfilerModules enum. 2893 * 2894 * \param flags Flags specifying profiler modules. 2895 * \param tag Profile tag. 2896 */ 2897 static void PauseProfilerEx(int flags, int tag = 0); 2898 2899 /** 2900 * Returns active (resumed) profiler modules. 2901 * See ProfilerModules enum. 2902 * 2903 * \returns active profiler modules. 2904 */ 2905 static int GetActiveProfilerModules(); 2906 2907 /** 2908 * If logging is performed into a memory buffer (via --logfile=*), allows to 2909 * retrieve previously written messages. This can be used for retrieving 2910 * profiler log data in the application. This function is thread-safe. 2911 * 2912 * Caller provides a destination buffer that must exist during GetLogLines 2913 * call. Only whole log lines are copied into the buffer. 2914 * 2915 * \param from_pos specified a point in a buffer to read from, 0 is the 2916 * beginning of a buffer. It is assumed that caller updates its current 2917 * position using returned size value from the previous call. 2918 * \param dest_buf destination buffer for log data. 2919 * \param max_size size of the destination buffer. 2920 * \returns actual size of log data copied into buffer. 2921 */ 2922 static int GetLogLines(int from_pos, char* dest_buf, int max_size); 2923 2924 /** 2925 * The minimum allowed size for a log lines buffer. If the size of 2926 * the buffer given will not be enough to hold a line of the maximum 2927 * length, an attempt to find a log line end in GetLogLines will 2928 * fail, and an empty result will be returned. 2929 */ 2930 static const int kMinimumSizeForLogLinesBuffer = 2048; 2931 2932 /** 2933 * Retrieve the V8 thread id of the calling thread. 2934 * 2935 * The thread id for a thread should only be retrieved after the V8 2936 * lock has been acquired with a Locker object with that thread. 2937 */ 2938 static int GetCurrentThreadId(); 2939 2940 /** 2941 * Forcefully terminate execution of a JavaScript thread. This can 2942 * be used to terminate long-running scripts. 2943 * 2944 * TerminateExecution should only be called when then V8 lock has 2945 * been acquired with a Locker object. Therefore, in order to be 2946 * able to terminate long-running threads, preemption must be 2947 * enabled to allow the user of TerminateExecution to acquire the 2948 * lock. 2949 * 2950 * The termination is achieved by throwing an exception that is 2951 * uncatchable by JavaScript exception handlers. Termination 2952 * exceptions act as if they were caught by a C++ TryCatch exception 2953 * handlers. If forceful termination is used, any C++ TryCatch 2954 * exception handler that catches an exception should check if that 2955 * exception is a termination exception and immediately return if 2956 * that is the case. Returning immediately in that case will 2957 * continue the propagation of the termination exception if needed. 2958 * 2959 * The thread id passed to TerminateExecution must have been 2960 * obtained by calling GetCurrentThreadId on the thread in question. 2961 * 2962 * \param thread_id The thread id of the thread to terminate. 2963 */ 2964 static void TerminateExecution(int thread_id); 2965 2966 /** 2967 * Forcefully terminate the current thread of JavaScript execution 2968 * in the given isolate. If no isolate is provided, the default 2969 * isolate is used. 2970 * 2971 * This method can be used by any thread even if that thread has not 2972 * acquired the V8 lock with a Locker object. 2973 * 2974 * \param isolate The isolate in which to terminate the current JS execution. 2975 */ 2976 static void TerminateExecution(Isolate* isolate = NULL); 2977 2978 /** 2979 * Is V8 terminating JavaScript execution. 2980 * 2981 * Returns true if JavaScript execution is currently terminating 2982 * because of a call to TerminateExecution. In that case there are 2983 * still JavaScript frames on the stack and the termination 2984 * exception is still active. 2985 */ 2986 static bool IsExecutionTerminating(); 2987 2988 /** 2989 * Releases any resources used by v8 and stops any utility threads 2990 * that may be running. Note that disposing v8 is permanent, it 2991 * cannot be reinitialized. 2992 * 2993 * It should generally not be necessary to dispose v8 before exiting 2994 * a process, this should happen automatically. It is only necessary 2995 * to use if the process needs the resources taken up by v8. 2996 */ 2997 static bool Dispose(); 2998 2999 /** 3000 * Get statistics about the heap memory usage. 3001 */ 3002 static void GetHeapStatistics(HeapStatistics* heap_statistics); 3003 3004 /** 3005 * Optional notification that the embedder is idle. 3006 * V8 uses the notification to reduce memory footprint. 3007 * This call can be used repeatedly if the embedder remains idle. 3008 * Returns true if the embedder should stop calling IdleNotification 3009 * until real work has been done. This indicates that V8 has done 3010 * as much cleanup as it will be able to do. 3011 */ 3012 static bool IdleNotification(); 3013 3014 /** 3015 * Optional notification that the system is running low on memory. 3016 * V8 uses these notifications to attempt to free memory. 3017 */ 3018 static void LowMemoryNotification(); 3019 3020 /** 3021 * Optional notification that a context has been disposed. V8 uses 3022 * these notifications to guide the GC heuristic. Returns the number 3023 * of context disposals - including this one - since the last time 3024 * V8 had a chance to clean up. 3025 */ 3026 static int ContextDisposedNotification(); 3027 3028 private: 3029 V8(); 3030 3031 static internal::Object** GlobalizeReference(internal::Object** handle); 3032 static void DisposeGlobal(internal::Object** global_handle); 3033 static void MakeWeak(internal::Object** global_handle, 3034 void* data, 3035 WeakReferenceCallback); 3036 static void ClearWeak(internal::Object** global_handle); 3037 static bool IsGlobalNearDeath(internal::Object** global_handle); 3038 static bool IsGlobalWeak(internal::Object** global_handle); 3039 static void SetWrapperClassId(internal::Object** global_handle, 3040 uint16_t class_id); 3041 3042 template <class T> friend class Handle; 3043 template <class T> friend class Local; 3044 template <class T> friend class Persistent; 3045 friend class Context; 3046 }; 3047 3048 3049 /** 3050 * An external exception handler. 3051 */ 3052 class V8EXPORT TryCatch { 3053 public: 3054 3055 /** 3056 * Creates a new try/catch block and registers it with v8. 3057 */ 3058 TryCatch(); 3059 3060 /** 3061 * Unregisters and deletes this try/catch block. 3062 */ 3063 ~TryCatch(); 3064 3065 /** 3066 * Returns true if an exception has been caught by this try/catch block. 3067 */ 3068 bool HasCaught() const; 3069 3070 /** 3071 * For certain types of exceptions, it makes no sense to continue 3072 * execution. 3073 * 3074 * Currently, the only type of exception that can be caught by a 3075 * TryCatch handler and for which it does not make sense to continue 3076 * is termination exception. Such exceptions are thrown when the 3077 * TerminateExecution methods are called to terminate a long-running 3078 * script. 3079 * 3080 * If CanContinue returns false, the correct action is to perform 3081 * any C++ cleanup needed and then return. 3082 */ 3083 bool CanContinue() const; 3084 3085 /** 3086 * Throws the exception caught by this TryCatch in a way that avoids 3087 * it being caught again by this same TryCatch. As with ThrowException 3088 * it is illegal to execute any JavaScript operations after calling 3089 * ReThrow; the caller must return immediately to where the exception 3090 * is caught. 3091 */ 3092 Handle<Value> ReThrow(); 3093 3094 /** 3095 * Returns the exception caught by this try/catch block. If no exception has 3096 * been caught an empty handle is returned. 3097 * 3098 * The returned handle is valid until this TryCatch block has been destroyed. 3099 */ 3100 Local<Value> Exception() const; 3101 3102 /** 3103 * Returns the .stack property of the thrown object. If no .stack 3104 * property is present an empty handle is returned. 3105 */ 3106 Local<Value> StackTrace() const; 3107 3108 /** 3109 * Returns the message associated with this exception. If there is 3110 * no message associated an empty handle is returned. 3111 * 3112 * The returned handle is valid until this TryCatch block has been 3113 * destroyed. 3114 */ 3115 Local<v8::Message> Message() const; 3116 3117 /** 3118 * Clears any exceptions that may have been caught by this try/catch block. 3119 * After this method has been called, HasCaught() will return false. 3120 * 3121 * It is not necessary to clear a try/catch block before using it again; if 3122 * another exception is thrown the previously caught exception will just be 3123 * overwritten. However, it is often a good idea since it makes it easier 3124 * to determine which operation threw a given exception. 3125 */ 3126 void Reset(); 3127 3128 /** 3129 * Set verbosity of the external exception handler. 3130 * 3131 * By default, exceptions that are caught by an external exception 3132 * handler are not reported. Call SetVerbose with true on an 3133 * external exception handler to have exceptions caught by the 3134 * handler reported as if they were not caught. 3135 */ 3136 void SetVerbose(bool value); 3137 3138 /** 3139 * Set whether or not this TryCatch should capture a Message object 3140 * which holds source information about where the exception 3141 * occurred. True by default. 3142 */ 3143 void SetCaptureMessage(bool value); 3144 3145 private: 3146 void* next_; 3147 void* exception_; 3148 void* message_; 3149 bool is_verbose_ : 1; 3150 bool can_continue_ : 1; 3151 bool capture_message_ : 1; 3152 bool rethrow_ : 1; 3153 3154 friend class v8::internal::Isolate; 3155 }; 3156 3157 3158 // --- C o n t e x t --- 3159 3160 3161 /** 3162 * Ignore 3163 */ 3164 class V8EXPORT ExtensionConfiguration { 3165 public: 3166 ExtensionConfiguration(int name_count, const char* names[]) 3167 : name_count_(name_count), names_(names) { } 3168 private: 3169 friend class ImplementationUtilities; 3170 int name_count_; 3171 const char** names_; 3172 }; 3173 3174 3175 /** 3176 * A sandboxed execution context with its own set of built-in objects 3177 * and functions. 3178 */ 3179 class V8EXPORT Context { 3180 public: 3181 /** 3182 * Returns the global proxy object or global object itself for 3183 * detached contexts. 3184 * 3185 * Global proxy object is a thin wrapper whose prototype points to 3186 * actual context's global object with the properties like Object, etc. 3187 * This is done that way for security reasons (for more details see 3188 * https://wiki.mozilla.org/Gecko:SplitWindow). 3189 * 3190 * Please note that changes to global proxy object prototype most probably 3191 * would break VM---v8 expects only global object as a prototype of 3192 * global proxy object. 3193 * 3194 * If DetachGlobal() has been invoked, Global() would return actual global 3195 * object until global is reattached with ReattachGlobal(). 3196 */ 3197 Local<Object> Global(); 3198 3199 /** 3200 * Detaches the global object from its context before 3201 * the global object can be reused to create a new context. 3202 */ 3203 void DetachGlobal(); 3204 3205 /** 3206 * Reattaches a global object to a context. This can be used to 3207 * restore the connection between a global object and a context 3208 * after DetachGlobal has been called. 3209 * 3210 * \param global_object The global object to reattach to the 3211 * context. For this to work, the global object must be the global 3212 * object that was associated with this context before a call to 3213 * DetachGlobal. 3214 */ 3215 void ReattachGlobal(Handle<Object> global_object); 3216 3217 /** Creates a new context. 3218 * 3219 * Returns a persistent handle to the newly allocated context. This 3220 * persistent handle has to be disposed when the context is no 3221 * longer used so the context can be garbage collected. 3222 * 3223 * \param extensions An optional extension configuration containing 3224 * the extensions to be installed in the newly created context. 3225 * 3226 * \param global_template An optional object template from which the 3227 * global object for the newly created context will be created. 3228 * 3229 * \param global_object An optional global object to be reused for 3230 * the newly created context. This global object must have been 3231 * created by a previous call to Context::New with the same global 3232 * template. The state of the global object will be completely reset 3233 * and only object identify will remain. 3234 */ 3235 static Persistent<Context> New( 3236 ExtensionConfiguration* extensions = NULL, 3237 Handle<ObjectTemplate> global_template = Handle<ObjectTemplate>(), 3238 Handle<Value> global_object = Handle<Value>()); 3239 3240 /** Returns the last entered context. */ 3241 static Local<Context> GetEntered(); 3242 3243 /** Returns the context that is on the top of the stack. */ 3244 static Local<Context> GetCurrent(); 3245 3246 /** 3247 * Returns the context of the calling JavaScript code. That is the 3248 * context of the top-most JavaScript frame. If there are no 3249 * JavaScript frames an empty handle is returned. 3250 */ 3251 static Local<Context> GetCalling(); 3252 3253 /** 3254 * Sets the security token for the context. To access an object in 3255 * another context, the security tokens must match. 3256 */ 3257 void SetSecurityToken(Handle<Value> token); 3258 3259 /** Restores the security token to the default value. */ 3260 void UseDefaultSecurityToken(); 3261 3262 /** Returns the security token of this context.*/ 3263 Handle<Value> GetSecurityToken(); 3264 3265 /** 3266 * Enter this context. After entering a context, all code compiled 3267 * and run is compiled and run in this context. If another context 3268 * is already entered, this old context is saved so it can be 3269 * restored when the new context is exited. 3270 */ 3271 void Enter(); 3272 3273 /** 3274 * Exit this context. Exiting the current context restores the 3275 * context that was in place when entering the current context. 3276 */ 3277 void Exit(); 3278 3279 /** Returns true if the context has experienced an out of memory situation. */ 3280 bool HasOutOfMemoryException(); 3281 3282 /** Returns true if V8 has a current context. */ 3283 static bool InContext(); 3284 3285 /** 3286 * Associate an additional data object with the context. This is mainly used 3287 * with the debugger to provide additional information on the context through 3288 * the debugger API. 3289 */ 3290 void SetData(Handle<String> data); 3291 Local<Value> GetData(); 3292 3293 /** 3294 * Stack-allocated class which sets the execution context for all 3295 * operations executed within a local scope. 3296 */ 3297 class Scope { 3298 public: 3299 explicit inline Scope(Handle<Context> context) : context_(context) { 3300 context_->Enter(); 3301 } 3302 inline ~Scope() { context_->Exit(); } 3303 private: 3304 Handle<Context> context_; 3305 }; 3306 3307 private: 3308 friend class Value; 3309 friend class Script; 3310 friend class Object; 3311 friend class Function; 3312 }; 3313 3314 3315 /** 3316 * Multiple threads in V8 are allowed, but only one thread at a time 3317 * is allowed to use any given V8 isolate. See Isolate class 3318 * comments. The definition of 'using V8 isolate' includes 3319 * accessing handles or holding onto object pointers obtained 3320 * from V8 handles while in the particular V8 isolate. It is up 3321 * to the user of V8 to ensure (perhaps with locking) that this 3322 * constraint is not violated. 3323 * 3324 * More then one thread and multiple V8 isolates can be used 3325 * without any locking if each isolate is created and accessed 3326 * by a single thread only. For example, one thread can use 3327 * multiple isolates or multiple threads can each create and run 3328 * their own isolate. 3329 * 3330 * If you wish to start using V8 isolate in more then one thread 3331 * you can do this by constructing a v8::Locker object to guard 3332 * access to the isolate. After the code using V8 has completed 3333 * for the current thread you can call the destructor. This can 3334 * be combined with C++ scope-based construction as follows 3335 * (assumes the default isolate that is used if not specified as 3336 * a parameter for the Locker): 3337 * 3338 * \code 3339 * ... 3340 * { 3341 * v8::Locker locker; 3342 * ... 3343 * // Code using V8 goes here. 3344 * ... 3345 * } // Destructor called here 3346 * \endcode 3347 * 3348 * If you wish to stop using V8 in a thread A you can do this by either 3349 * by destroying the v8::Locker object as above or by constructing a 3350 * v8::Unlocker object: 3351 * 3352 * \code 3353 * { 3354 * v8::Unlocker unlocker; 3355 * ... 3356 * // Code not using V8 goes here while V8 can run in another thread. 3357 * ... 3358 * } // Destructor called here. 3359 * \endcode 3360 * 3361 * The Unlocker object is intended for use in a long-running callback 3362 * from V8, where you want to release the V8 lock for other threads to 3363 * use. 3364 * 3365 * The v8::Locker is a recursive lock. That is, you can lock more than 3366 * once in a given thread. This can be useful if you have code that can 3367 * be called either from code that holds the lock or from code that does 3368 * not. The Unlocker is not recursive so you can not have several 3369 * Unlockers on the stack at once, and you can not use an Unlocker in a 3370 * thread that is not inside a Locker's scope. 3371 * 3372 * An unlocker will unlock several lockers if it has to and reinstate 3373 * the correct depth of locking on its destruction. eg.: 3374 * 3375 * \code 3376 * // V8 not locked. 3377 * { 3378 * v8::Locker locker; 3379 * // V8 locked. 3380 * { 3381 * v8::Locker another_locker; 3382 * // V8 still locked (2 levels). 3383 * { 3384 * v8::Unlocker unlocker; 3385 * // V8 not locked. 3386 * } 3387 * // V8 locked again (2 levels). 3388 * } 3389 * // V8 still locked (1 level). 3390 * } 3391 * // V8 Now no longer locked. 3392 * \endcode 3393 */ 3394 class V8EXPORT Unlocker { 3395 public: 3396 Unlocker(); 3397 ~Unlocker(); 3398 }; 3399 3400 3401 class V8EXPORT Locker { 3402 public: 3403 Locker(); 3404 ~Locker(); 3405 3406 /** 3407 * Start preemption. 3408 * 3409 * When preemption is started, a timer is fired every n milli seconds 3410 * that will switch between multiple threads that are in contention 3411 * for the V8 lock. 3412 */ 3413 static void StartPreemption(int every_n_ms); 3414 3415 /** 3416 * Stop preemption. 3417 */ 3418 static void StopPreemption(); 3419 3420 /** 3421 * Returns whether or not the locker is locked by the current thread. 3422 */ 3423 static bool IsLocked(); 3424 3425 /** 3426 * Returns whether v8::Locker is being used by this V8 instance. 3427 */ 3428 static bool IsActive() { return active_; } 3429 3430 private: 3431 bool has_lock_; 3432 bool top_level_; 3433 3434 static bool active_; 3435 3436 // Disallow copying and assigning. 3437 Locker(const Locker&); 3438 void operator=(const Locker&); 3439 }; 3440 3441 3442 /** 3443 * An interface for exporting data from V8, using "push" model. 3444 */ 3445 class V8EXPORT OutputStream { // NOLINT 3446 public: 3447 enum OutputEncoding { 3448 kAscii = 0 // 7-bit ASCII. 3449 }; 3450 enum WriteResult { 3451 kContinue = 0, 3452 kAbort = 1 3453 }; 3454 virtual ~OutputStream() {} 3455 /** Notify about the end of stream. */ 3456 virtual void EndOfStream() = 0; 3457 /** Get preferred output chunk size. Called only once. */ 3458 virtual int GetChunkSize() { return 1024; } 3459 /** Get preferred output encoding. Called only once. */ 3460 virtual OutputEncoding GetOutputEncoding() { return kAscii; } 3461 /** 3462 * Writes the next chunk of snapshot data into the stream. Writing 3463 * can be stopped by returning kAbort as function result. EndOfStream 3464 * will not be called in case writing was aborted. 3465 */ 3466 virtual WriteResult WriteAsciiChunk(char* data, int size) = 0; 3467 }; 3468 3469 3470 /** 3471 * An interface for reporting progress and controlling long-running 3472 * activities. 3473 */ 3474 class V8EXPORT ActivityControl { // NOLINT 3475 public: 3476 enum ControlOption { 3477 kContinue = 0, 3478 kAbort = 1 3479 }; 3480 virtual ~ActivityControl() {} 3481 /** 3482 * Notify about current progress. The activity can be stopped by 3483 * returning kAbort as the callback result. 3484 */ 3485 virtual ControlOption ReportProgressValue(int done, int total) = 0; 3486 }; 3487 3488 3489 // --- I m p l e m e n t a t i o n --- 3490 3491 3492 namespace internal { 3493 3494 static const int kApiPointerSize = sizeof(void*); // NOLINT 3495 static const int kApiIntSize = sizeof(int); // NOLINT 3496 3497 // Tag information for HeapObject. 3498 const int kHeapObjectTag = 1; 3499 const int kHeapObjectTagSize = 2; 3500 const intptr_t kHeapObjectTagMask = (1 << kHeapObjectTagSize) - 1; 3501 3502 // Tag information for Smi. 3503 const int kSmiTag = 0; 3504 const int kSmiTagSize = 1; 3505 const intptr_t kSmiTagMask = (1 << kSmiTagSize) - 1; 3506 3507 template <size_t ptr_size> struct SmiTagging; 3508 3509 // Smi constants for 32-bit systems. 3510 template <> struct SmiTagging<4> { 3511 static const int kSmiShiftSize = 0; 3512 static const int kSmiValueSize = 31; 3513 static inline int SmiToInt(internal::Object* value) { 3514 int shift_bits = kSmiTagSize + kSmiShiftSize; 3515 // Throw away top 32 bits and shift down (requires >> to be sign extending). 3516 return static_cast<int>(reinterpret_cast<intptr_t>(value)) >> shift_bits; 3517 } 3518 3519 // For 32-bit systems any 2 bytes aligned pointer can be encoded as smi 3520 // with a plain reinterpret_cast. 3521 static const uintptr_t kEncodablePointerMask = 0x1; 3522 static const int kPointerToSmiShift = 0; 3523 }; 3524 3525 // Smi constants for 64-bit systems. 3526 template <> struct SmiTagging<8> { 3527 static const int kSmiShiftSize = 31; 3528 static const int kSmiValueSize = 32; 3529 static inline int SmiToInt(internal::Object* value) { 3530 int shift_bits = kSmiTagSize + kSmiShiftSize; 3531 // Shift down and throw away top 32 bits. 3532 return static_cast<int>(reinterpret_cast<intptr_t>(value) >> shift_bits); 3533 } 3534 3535 // To maximize the range of pointers that can be encoded 3536 // in the available 32 bits, we require them to be 8 bytes aligned. 3537 // This gives 2 ^ (32 + 3) = 32G address space covered. 3538 // It might be not enough to cover stack allocated objects on some platforms. 3539 static const int kPointerAlignment = 3; 3540 3541 static const uintptr_t kEncodablePointerMask = 3542 ~(uintptr_t(0xffffffff) << kPointerAlignment); 3543 3544 static const int kPointerToSmiShift = 3545 kSmiTagSize + kSmiShiftSize - kPointerAlignment; 3546 }; 3547 3548 typedef SmiTagging<kApiPointerSize> PlatformSmiTagging; 3549 const int kSmiShiftSize = PlatformSmiTagging::kSmiShiftSize; 3550 const int kSmiValueSize = PlatformSmiTagging::kSmiValueSize; 3551 const uintptr_t kEncodablePointerMask = 3552 PlatformSmiTagging::kEncodablePointerMask; 3553 const int kPointerToSmiShift = PlatformSmiTagging::kPointerToSmiShift; 3554 3555 template <size_t ptr_size> struct InternalConstants; 3556 3557 // Internal constants for 32-bit systems. 3558 template <> struct InternalConstants<4> { 3559 static const int kStringResourceOffset = 3 * kApiPointerSize; 3560 }; 3561 3562 // Internal constants for 64-bit systems. 3563 template <> struct InternalConstants<8> { 3564 static const int kStringResourceOffset = 3 * kApiPointerSize; 3565 }; 3566 3567 /** 3568 * This class exports constants and functionality from within v8 that 3569 * is necessary to implement inline functions in the v8 api. Don't 3570 * depend on functions and constants defined here. 3571 */ 3572 class Internals { 3573 public: 3574 3575 // These values match non-compiler-dependent values defined within 3576 // the implementation of v8. 3577 static const int kHeapObjectMapOffset = 0; 3578 static const int kMapInstanceTypeOffset = 1 * kApiPointerSize + kApiIntSize; 3579 static const int kStringResourceOffset = 3580 InternalConstants<kApiPointerSize>::kStringResourceOffset; 3581 3582 static const int kProxyProxyOffset = kApiPointerSize; 3583 static const int kJSObjectHeaderSize = 3 * kApiPointerSize; 3584 static const int kFullStringRepresentationMask = 0x07; 3585 static const int kExternalTwoByteRepresentationTag = 0x02; 3586 3587 static const int kJSObjectType = 0xa0; 3588 static const int kFirstNonstringType = 0x80; 3589 static const int kProxyType = 0x85; 3590 3591 static inline bool HasHeapObjectTag(internal::Object* value) { 3592 return ((reinterpret_cast<intptr_t>(value) & kHeapObjectTagMask) == 3593 kHeapObjectTag); 3594 } 3595 3596 static inline bool HasSmiTag(internal::Object* value) { 3597 return ((reinterpret_cast<intptr_t>(value) & kSmiTagMask) == kSmiTag); 3598 } 3599 3600 static inline int SmiValue(internal::Object* value) { 3601 return PlatformSmiTagging::SmiToInt(value); 3602 } 3603 3604 static inline int GetInstanceType(internal::Object* obj) { 3605 typedef internal::Object O; 3606 O* map = ReadField<O*>(obj, kHeapObjectMapOffset); 3607 return ReadField<uint8_t>(map, kMapInstanceTypeOffset); 3608 } 3609 3610 static inline void* GetExternalPointerFromSmi(internal::Object* value) { 3611 const uintptr_t address = reinterpret_cast<uintptr_t>(value); 3612 return reinterpret_cast<void*>(address >> kPointerToSmiShift); 3613 } 3614 3615 static inline void* GetExternalPointer(internal::Object* obj) { 3616 if (HasSmiTag(obj)) { 3617 return GetExternalPointerFromSmi(obj); 3618 } else if (GetInstanceType(obj) == kProxyType) { 3619 return ReadField<void*>(obj, kProxyProxyOffset); 3620 } else { 3621 return NULL; 3622 } 3623 } 3624 3625 static inline bool IsExternalTwoByteString(int instance_type) { 3626 int representation = (instance_type & kFullStringRepresentationMask); 3627 return representation == kExternalTwoByteRepresentationTag; 3628 } 3629 3630 template <typename T> 3631 static inline T ReadField(Object* ptr, int offset) { 3632 uint8_t* addr = reinterpret_cast<uint8_t*>(ptr) + offset - kHeapObjectTag; 3633 return *reinterpret_cast<T*>(addr); 3634 } 3635 3636 static inline bool CanCastToHeapObject(void* o) { return false; } 3637 static inline bool CanCastToHeapObject(Context* o) { return true; } 3638 static inline bool CanCastToHeapObject(String* o) { return true; } 3639 static inline bool CanCastToHeapObject(Object* o) { return true; } 3640 static inline bool CanCastToHeapObject(Message* o) { return true; } 3641 static inline bool CanCastToHeapObject(StackTrace* o) { return true; } 3642 static inline bool CanCastToHeapObject(StackFrame* o) { return true; } 3643 }; 3644 3645 } // namespace internal 3646 3647 3648 template <class T> 3649 Handle<T>::Handle() : val_(0) { } 3650 3651 3652 template <class T> 3653 Local<T>::Local() : Handle<T>() { } 3654 3655 3656 template <class T> 3657 Local<T> Local<T>::New(Handle<T> that) { 3658 if (that.IsEmpty()) return Local<T>(); 3659 T* that_ptr = *that; 3660 internal::Object** p = reinterpret_cast<internal::Object**>(that_ptr); 3661 if (internal::Internals::CanCastToHeapObject(that_ptr)) { 3662 return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle( 3663 reinterpret_cast<internal::HeapObject*>(*p)))); 3664 } 3665 return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(*p))); 3666 } 3667 3668 3669 template <class T> 3670 Persistent<T> Persistent<T>::New(Handle<T> that) { 3671 if (that.IsEmpty()) return Persistent<T>(); 3672 internal::Object** p = reinterpret_cast<internal::Object**>(*that); 3673 return Persistent<T>(reinterpret_cast<T*>(V8::GlobalizeReference(p))); 3674 } 3675 3676 3677 template <class T> 3678 bool Persistent<T>::IsNearDeath() const { 3679 if (this->IsEmpty()) return false; 3680 return V8::IsGlobalNearDeath(reinterpret_cast<internal::Object**>(**this)); 3681 } 3682 3683 3684 template <class T> 3685 bool Persistent<T>::IsWeak() const { 3686 if (this->IsEmpty()) return false; 3687 return V8::IsGlobalWeak(reinterpret_cast<internal::Object**>(**this)); 3688 } 3689 3690 3691 template <class T> 3692 void Persistent<T>::Dispose() { 3693 if (this->IsEmpty()) return; 3694 V8::DisposeGlobal(reinterpret_cast<internal::Object**>(**this)); 3695 } 3696 3697 3698 template <class T> 3699 Persistent<T>::Persistent() : Handle<T>() { } 3700 3701 template <class T> 3702 void Persistent<T>::MakeWeak(void* parameters, WeakReferenceCallback callback) { 3703 V8::MakeWeak(reinterpret_cast<internal::Object**>(**this), 3704 parameters, 3705 callback); 3706 } 3707 3708 template <class T> 3709 void Persistent<T>::ClearWeak() { 3710 V8::ClearWeak(reinterpret_cast<internal::Object**>(**this)); 3711 } 3712 3713 template <class T> 3714 void Persistent<T>::SetWrapperClassId(uint16_t class_id) { 3715 V8::SetWrapperClassId(reinterpret_cast<internal::Object**>(**this), class_id); 3716 } 3717 3718 Arguments::Arguments(internal::Object** implicit_args, 3719 internal::Object** values, int length, 3720 bool is_construct_call) 3721 : implicit_args_(implicit_args), 3722 values_(values), 3723 length_(length), 3724 is_construct_call_(is_construct_call) { } 3725 3726 3727 Local<Value> Arguments::operator[](int i) const { 3728 if (i < 0 || length_ <= i) return Local<Value>(*Undefined()); 3729 return Local<Value>(reinterpret_cast<Value*>(values_ - i)); 3730 } 3731 3732 3733 Local<Function> Arguments::Callee() const { 3734 return Local<Function>(reinterpret_cast<Function*>( 3735 &implicit_args_[kCalleeIndex])); 3736 } 3737 3738 3739 Local<Object> Arguments::This() const { 3740 return Local<Object>(reinterpret_cast<Object*>(values_ + 1)); 3741 } 3742 3743 3744 Local<Object> Arguments::Holder() const { 3745 return Local<Object>(reinterpret_cast<Object*>( 3746 &implicit_args_[kHolderIndex])); 3747 } 3748 3749 3750 Local<Value> Arguments::Data() const { 3751 return Local<Value>(reinterpret_cast<Value*>(&implicit_args_[kDataIndex])); 3752 } 3753 3754 3755 bool Arguments::IsConstructCall() const { 3756 return is_construct_call_; 3757 } 3758 3759 3760 int Arguments::Length() const { 3761 return length_; 3762 } 3763 3764 3765 template <class T> 3766 Local<T> HandleScope::Close(Handle<T> value) { 3767 internal::Object** before = reinterpret_cast<internal::Object**>(*value); 3768 internal::Object** after = RawClose(before); 3769 return Local<T>(reinterpret_cast<T*>(after)); 3770 } 3771 3772 Handle<Value> ScriptOrigin::ResourceName() const { 3773 return resource_name_; 3774 } 3775 3776 3777 Handle<Integer> ScriptOrigin::ResourceLineOffset() const { 3778 return resource_line_offset_; 3779 } 3780 3781 3782 Handle<Integer> ScriptOrigin::ResourceColumnOffset() const { 3783 return resource_column_offset_; 3784 } 3785 3786 3787 Handle<Boolean> Boolean::New(bool value) { 3788 return value ? True() : False(); 3789 } 3790 3791 3792 void Template::Set(const char* name, v8::Handle<Data> value) { 3793 Set(v8::String::New(name), value); 3794 } 3795 3796 3797 Local<Value> Object::GetInternalField(int index) { 3798 #ifndef V8_ENABLE_CHECKS 3799 Local<Value> quick_result = UncheckedGetInternalField(index); 3800 if (!quick_result.IsEmpty()) return quick_result; 3801 #endif 3802 return CheckedGetInternalField(index); 3803 } 3804 3805 3806 Local<Value> Object::UncheckedGetInternalField(int index) { 3807 typedef internal::Object O; 3808 typedef internal::Internals I; 3809 O* obj = *reinterpret_cast<O**>(this); 3810 if (I::GetInstanceType(obj) == I::kJSObjectType) { 3811 // If the object is a plain JSObject, which is the common case, 3812 // we know where to find the internal fields and can return the 3813 // value directly. 3814 int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index); 3815 O* value = I::ReadField<O*>(obj, offset); 3816 O** result = HandleScope::CreateHandle(value); 3817 return Local<Value>(reinterpret_cast<Value*>(result)); 3818 } else { 3819 return Local<Value>(); 3820 } 3821 } 3822 3823 3824 void* External::Unwrap(Handle<v8::Value> obj) { 3825 #ifdef V8_ENABLE_CHECKS 3826 return FullUnwrap(obj); 3827 #else 3828 return QuickUnwrap(obj); 3829 #endif 3830 } 3831 3832 3833 void* External::QuickUnwrap(Handle<v8::Value> wrapper) { 3834 typedef internal::Object O; 3835 O* obj = *reinterpret_cast<O**>(const_cast<v8::Value*>(*wrapper)); 3836 return internal::Internals::GetExternalPointer(obj); 3837 } 3838 3839 3840 void* Object::GetPointerFromInternalField(int index) { 3841 typedef internal::Object O; 3842 typedef internal::Internals I; 3843 3844 O* obj = *reinterpret_cast<O**>(this); 3845 3846 if (I::GetInstanceType(obj) == I::kJSObjectType) { 3847 // If the object is a plain JSObject, which is the common case, 3848 // we know where to find the internal fields and can return the 3849 // value directly. 3850 int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index); 3851 O* value = I::ReadField<O*>(obj, offset); 3852 return I::GetExternalPointer(value); 3853 } 3854 3855 return SlowGetPointerFromInternalField(index); 3856 } 3857 3858 3859 String* String::Cast(v8::Value* value) { 3860 #ifdef V8_ENABLE_CHECKS 3861 CheckCast(value); 3862 #endif 3863 return static_cast<String*>(value); 3864 } 3865 3866 3867 String::ExternalStringResource* String::GetExternalStringResource() const { 3868 typedef internal::Object O; 3869 typedef internal::Internals I; 3870 O* obj = *reinterpret_cast<O**>(const_cast<String*>(this)); 3871 String::ExternalStringResource* result; 3872 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) { 3873 void* value = I::ReadField<void*>(obj, I::kStringResourceOffset); 3874 result = reinterpret_cast<String::ExternalStringResource*>(value); 3875 } else { 3876 result = NULL; 3877 } 3878 #ifdef V8_ENABLE_CHECKS 3879 VerifyExternalStringResource(result); 3880 #endif 3881 return result; 3882 } 3883 3884 3885 bool Value::IsString() const { 3886 #ifdef V8_ENABLE_CHECKS 3887 return FullIsString(); 3888 #else 3889 return QuickIsString(); 3890 #endif 3891 } 3892 3893 bool Value::QuickIsString() const { 3894 typedef internal::Object O; 3895 typedef internal::Internals I; 3896 O* obj = *reinterpret_cast<O**>(const_cast<Value*>(this)); 3897 if (!I::HasHeapObjectTag(obj)) return false; 3898 return (I::GetInstanceType(obj) < I::kFirstNonstringType); 3899 } 3900 3901 3902 Number* Number::Cast(v8::Value* value) { 3903 #ifdef V8_ENABLE_CHECKS 3904 CheckCast(value); 3905 #endif 3906 return static_cast<Number*>(value); 3907 } 3908 3909 3910 Integer* Integer::Cast(v8::Value* value) { 3911 #ifdef V8_ENABLE_CHECKS 3912 CheckCast(value); 3913 #endif 3914 return static_cast<Integer*>(value); 3915 } 3916 3917 3918 Date* Date::Cast(v8::Value* value) { 3919 #ifdef V8_ENABLE_CHECKS 3920 CheckCast(value); 3921 #endif 3922 return static_cast<Date*>(value); 3923 } 3924 3925 3926 RegExp* RegExp::Cast(v8::Value* value) { 3927 #ifdef V8_ENABLE_CHECKS 3928 CheckCast(value); 3929 #endif 3930 return static_cast<RegExp*>(value); 3931 } 3932 3933 3934 Object* Object::Cast(v8::Value* value) { 3935 #ifdef V8_ENABLE_CHECKS 3936 CheckCast(value); 3937 #endif 3938 return static_cast<Object*>(value); 3939 } 3940 3941 3942 Array* Array::Cast(v8::Value* value) { 3943 #ifdef V8_ENABLE_CHECKS 3944 CheckCast(value); 3945 #endif 3946 return static_cast<Array*>(value); 3947 } 3948 3949 3950 Function* Function::Cast(v8::Value* value) { 3951 #ifdef V8_ENABLE_CHECKS 3952 CheckCast(value); 3953 #endif 3954 return static_cast<Function*>(value); 3955 } 3956 3957 3958 External* External::Cast(v8::Value* value) { 3959 #ifdef V8_ENABLE_CHECKS 3960 CheckCast(value); 3961 #endif 3962 return static_cast<External*>(value); 3963 } 3964 3965 3966 Local<Value> AccessorInfo::Data() const { 3967 return Local<Value>(reinterpret_cast<Value*>(&args_[-2])); 3968 } 3969 3970 3971 Local<Object> AccessorInfo::This() const { 3972 return Local<Object>(reinterpret_cast<Object*>(&args_[0])); 3973 } 3974 3975 3976 Local<Object> AccessorInfo::Holder() const { 3977 return Local<Object>(reinterpret_cast<Object*>(&args_[-1])); 3978 } 3979 3980 3981 /** 3982 * \example shell.cc 3983 * A simple shell that takes a list of expressions on the 3984 * command-line and executes them. 3985 */ 3986 3987 3988 /** 3989 * \example process.cc 3990 */ 3991 3992 3993 } // namespace v8 3994 3995 3996 #undef V8EXPORT 3997 #undef TYPE_CHECK 3998 3999 4000 #endif // V8_H_ 4001