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