v8.h 78.6 KB
Newer Older
1
// Copyright 2007-2008 the V8 project authors. All rights reserved.
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//     * Redistributions of source code must retain the above copyright
//       notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
//       copyright notice, this list of conditions and the following
//       disclaimer in the documentation and/or other materials provided
//       with the distribution.
//     * Neither the name of Google Inc. nor the names of its
//       contributors may be used to endorse or promote products derived
//       from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

28
/** \mainpage V8 API Reference Guide
29 30
 *
 * V8 is Google's open source JavaScript engine.
31 32 33 34 35
 *
 * This set of documents provides reference material generated from the
 * V8 header file, include/v8.h.
 *
 * For other documentation see http://code.google.com/apis/v8/
36
 */
37

38 39
#ifndef V8_H_
#define V8_H_
40 41 42 43

#include <stdio.h>

#ifdef _WIN32
44 45 46 47
// When compiling on MinGW stdint.h is available.
#ifdef __MINGW32__
#include <stdint.h>
#else  // __MINGW32__
48 49 50 51
typedef signed char int8_t;
typedef unsigned char uint8_t;
typedef short int16_t;  // NOLINT
typedef unsigned short uint16_t;  // NOLINT
52 53
typedef int int32_t;
typedef unsigned int uint32_t;
54 55
typedef __int64 int64_t;
typedef unsigned __int64 uint64_t;
56 57
// intptr_t and friends are defined in crtdefs.h through stdio.h.
#endif  // __MINGW32__
58 59 60 61 62 63

// Setup for Windows DLL export/import. When building the V8 DLL the
// BUILDING_V8_SHARED needs to be defined. When building a program which uses
// the V8 DLL USING_V8_SHARED needs to be defined. When either building the V8
// static library or building a program which uses the V8 static library neither
// BUILDING_V8_SHARED nor USING_V8_SHARED should be defined.
64 65
// The reason for having both V8EXPORT and V8EXPORT_INLINE is that classes which
// have their code inside this header file need to have __declspec(dllexport)
66 67 68 69 70 71 72 73
// when building the DLL but cannot have __declspec(dllimport) when building
// a program which uses the DLL.
#if defined(BUILDING_V8_SHARED) && defined(USING_V8_SHARED)
#error both BUILDING_V8_SHARED and USING_V8_SHARED are set - please check the\
  build configuration to ensure that at most one of these is set
#endif

#ifdef BUILDING_V8_SHARED
74 75
#define V8EXPORT __declspec(dllexport)
#define V8EXPORT_INLINE __declspec(dllexport)
76
#elif USING_V8_SHARED
77 78
#define V8EXPORT __declspec(dllimport)
#define V8EXPORT_INLINE
79
#else
80 81
#define V8EXPORT
#define V8EXPORT_INLINE
82 83 84
#endif  // BUILDING_V8_SHARED

#else  // _WIN32
85

86
#include <stdint.h>
87 88 89 90

// Setup for Linux shared library export. There is no need to destinguish
// neither between building or using the V8 shared library nor between using
// the shared or static V8 library as there is on Windows. Therefore there is
91
// no checking of BUILDING_V8_SHARED and USING_V8_SHARED.
92
#if defined(__GNUC__) && (__GNUC__ >= 4)
93 94
#define V8EXPORT __attribute__ ((visibility("default")))
#define V8EXPORT_INLINE __attribute__ ((visibility("default")))
95
#else  // defined(__GNUC__) && (__GNUC__ >= 4)
96 97
#define V8EXPORT
#define V8EXPORT_INLINE
98 99 100
#endif  // defined(__GNUC__) && (__GNUC__ >= 4)

#endif  // _WIN32
101 102

/**
103
 * The v8 JavaScript engine.
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
 */
namespace v8 {

class Context;
class String;
class Value;
class Utils;
class Number;
class Object;
class Array;
class Int32;
class Uint32;
class External;
class Primitive;
class Boolean;
class Integer;
class Function;
class Date;
class ImplementationUtilities;
class Signature;
template <class T> class Handle;
template <class T> class Local;
template <class T> class Persistent;
class FunctionTemplate;
class ObjectTemplate;
class Data;


// --- W e a k  H a n d l e s


/**
 * A weak reference callback function.
 *
 * \param object the weak global object to be reclaimed by the garbage collector
 * \param parameter the value passed in when making the weak global object
 */
141
typedef void (*WeakReferenceCallback)(Persistent<Value> object,
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
                                      void* parameter);


// --- H a n d l e s ---

#define TYPE_CHECK(T, S)                              \
  while (false) {                                     \
    *(static_cast<T**>(0)) = static_cast<S*>(0);      \
  }

/**
 * An object reference managed by the v8 garbage collector.
 *
 * All objects returned from v8 have to be tracked by the garbage
 * collector so that it knows that the objects are still alive.  Also,
 * because the garbage collector may move objects, it is unsafe to
 * point directly to an object.  Instead, all objects are stored in
 * handles which are known by the garbage collector and updated
 * whenever an object moves.  Handles should always be passed by value
 * (except in cases like out-parameters) and they should never be
 * allocated on the heap.
 *
 * There are two types of handles: local and persistent handles.
 * Local handles are light-weight and transient and typically used in
 * local operations.  They are managed by HandleScopes.  Persistent
 * handles can be used when storing objects across several independent
 * operations and have to be explicitly deallocated when they're no
 * longer used.
 *
 * It is safe to extract the object stored in the handle by
 * dereferencing the handle (for instance, to extract the Object* from
 * an Handle<Object>); the value will still be governed by a handle
 * behind the scenes and the same rules apply to these values as to
 * their handles.
 */
177
template <class T> class V8EXPORT_INLINE Handle {
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
 public:

  /**
   * Creates an empty handle.
   */
  Handle();

  /**
   * Creates a new handle for the specified value.
   */
  explicit Handle(T* val) : val_(val) { }

  /**
   * Creates a handle for the contents of the specified handle.  This
   * constructor allows you to pass handles as arguments by value and
193
   * to assign between handles.  However, if you try to assign between
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
   * incompatible handles, for instance from a Handle<String> to a
   * Handle<Number> it will cause a compiletime error.  Assigning
   * between compatible handles, for instance assigning a
   * Handle<String> to a variable declared as Handle<Value>, is legal
   * because String is a subclass of Value.
   */
  template <class S> inline Handle(Handle<S> that)
      : val_(reinterpret_cast<T*>(*that)) {
    /**
     * This check fails when trying to convert between incompatible
     * handles. For example, converting from a Handle<String> to a
     * Handle<Number>.
     */
    TYPE_CHECK(T, S);
  }

  /**
   * Returns true if the handle is empty.
   */
213
  bool IsEmpty() const { return val_ == 0; }
214

215
  T* operator->() const;
216

217
  T* operator*() const;
218 219 220 221 222 223 224 225 226 227 228 229

  /**
   * Sets the handle to be empty. IsEmpty() will then return true.
   */
  void Clear() { this->val_ = 0; }

  /**
   * Checks whether two handles are the same.
   * Returns true if both are empty, or if the objects
   * to which they refer are identical.
   * The handles' references are not checked.
   */
230
  template <class S> bool operator==(Handle<S> that) const {
231 232 233 234 235 236 237 238 239 240 241 242 243
    void** a = reinterpret_cast<void**>(**this);
    void** b = reinterpret_cast<void**>(*that);
    if (a == 0) return b == 0;
    if (b == 0) return false;
    return *a == *b;
  }

  /**
   * Checks whether two handles are different.
   * Returns true if only one of the handles is empty, or if
   * the objects to which they refer are different.
   * The handles' references are not checked.
   */
244
  template <class S> bool operator!=(Handle<S> that) const {
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
    return !operator==(that);
  }

  template <class S> static inline Handle<T> Cast(Handle<S> that) {
    if (that.IsEmpty()) return Handle<T>();
    return Handle<T>(T::Cast(*that));
  }

 private:
  T* val_;
};


/**
 * A light-weight stack-allocated object handle.  All operations
 * that return objects from within v8 return them in local handles.  They
 * are created within HandleScopes, and all local handles allocated within a
 * handle scope are destroyed when the handle scope is destroyed.  Hence it
 * is not necessary to explicitly deallocate local handles.
 */
265
template <class T> class V8EXPORT_INLINE Local : public Handle<T> {
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292
 public:
  Local();
  template <class S> inline Local(Local<S> that)
      : Handle<T>(reinterpret_cast<T*>(*that)) {
    /**
     * This check fails when trying to convert between incompatible
     * handles. For example, converting from a Handle<String> to a
     * Handle<Number>.
     */
    TYPE_CHECK(T, S);
  }
  template <class S> inline Local(S* that) : Handle<T>(that) { }
  template <class S> static inline Local<T> Cast(Local<S> that) {
    if (that.IsEmpty()) return Local<T>();
    return Local<T>(T::Cast(*that));
  }

  /** Create a local handle for the content of another handle.
   *  The referee is kept alive by the local handle even when
   *  the original handle is destroyed/disposed.
   */
  static Local<T> New(Handle<T> that);
};


/**
 * An object reference that is independent of any handle scope.  Where
293
 * a Local handle only lives as long as the HandleScope in which it was
294 295 296 297 298 299 300 301 302 303 304 305 306 307
 * allocated, a Persistent handle remains valid until it is explicitly
 * disposed.
 *
 * A persistent handle contains a reference to a storage cell within
 * the v8 engine which holds an object value and which is updated by
 * the garbage collector whenever the object is moved.  A new storage
 * cell can be created using Persistent::New and existing handles can
 * be disposed using Persistent::Dispose.  Since persistent handles
 * are passed by value you may have many persistent handle objects
 * that point to the same storage cell.  For instance, if you pass a
 * persistent handle as an argument to a function you will not get two
 * different storage cells but rather two references to the same
 * storage cell.
 */
308
template <class T> class V8EXPORT_INLINE Persistent : public Handle<T> {
309 310 311 312 313 314 315 316 317 318 319 320
 public:

  /**
   * Creates an empty persistent handle that doesn't point to any
   * storage cell.
   */
  Persistent();

  /**
   * Creates a persistent handle for the same storage cell as the
   * specified handle.  This constructor allows you to pass persistent
   * handles as arguments by value and to assign between persistent
321
   * handles.  However, attempting to assign between incompatible
322
   * persistent handles, for instance from a Persistent<String> to a
323
   * Persistent<Number> will cause a compiletime error.  Assigning
324 325
   * between compatible persistent handles, for instance assigning a
   * Persistent<String> to a variable declared as Persistent<Value>,
326
   * is allowed as String is a subclass of Value.
327 328 329 330 331 332 333 334 335 336 337 338 339
   */
  template <class S> inline Persistent(Persistent<S> that)
      : Handle<T>(reinterpret_cast<T*>(*that)) {
    /**
     * This check fails when trying to convert between incompatible
     * handles. For example, converting from a Handle<String> to a
     * Handle<Number>.
     */
    TYPE_CHECK(T, S);
  }

  template <class S> inline Persistent(S* that) : Handle<T>(that) { }

340 341 342 343
  /**
   * "Casts" a plain handle which is known to be a persistent handle
   * to a persistent handle.
   */
344 345 346 347 348 349 350 351 352
  template <class S> explicit inline Persistent(Handle<S> that)
      : Handle<T>(*that) { }

  template <class S> static inline Persistent<T> Cast(Persistent<S> that) {
    if (that.IsEmpty()) return Persistent<T>();
    return Persistent<T>(T::Cast(*that));
  }

  /**
353 354
   * Creates a new persistent handle for an existing local or
   * persistent handle.
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
   */
  static Persistent<T> New(Handle<T> that);

  /**
   * Releases the storage cell referenced by this persistent handle.
   * Does not remove the reference to the cell from any handles.
   * This handle's reference, and any any other references to the storage
   * cell remain and IsEmpty will still return false.
   */
  void Dispose();

  /**
   * Make the reference to this object weak.  When only weak handles
   * refer to the object, the garbage collector will perform a
   * callback to the given V8::WeakReferenceCallback function, passing
   * it the object reference and the given parameters.
   */
  void MakeWeak(void* parameters, WeakReferenceCallback callback);

  /** Clears the weak reference to this object.*/
  void ClearWeak();

  /**
   *Checks if the handle holds the only reference to an object.
   */
380
  bool IsNearDeath() const;
381 382 383 384

  /**
   * Returns true if the handle's reference is weak.
   */
385
  bool IsWeak() const;
386 387 388 389 390 391 392

 private:
  friend class ImplementationUtilities;
  friend class ObjectTemplate;
};


393
 /**
394 395 396 397 398
 * A stack-allocated class that governs a number of local handles.
 * After a handle scope has been created, all local handles will be
 * allocated within that handle scope until either the handle scope is
 * deleted or another handle scope is created.  If there is already a
 * handle scope and a new one is created, all allocations will take
399
 * place in the new handle scope until it is deleted.  After that,
400 401 402 403 404 405 406
 * new handles will again be allocated in the original handle scope.
 *
 * After the handle scope of a local handle has been deleted the
 * garbage collector will no longer track the object stored in the
 * handle and may deallocate it.  The behavior of accessing a handle
 * for which the handle scope has been deleted is undefined.
 */
407
class V8EXPORT HandleScope {
408
 public:
409
  HandleScope();
410

411
  ~HandleScope();
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436

  /**
   * Closes the handle scope and returns the value as a handle in the
   * previous scope, which is the new current scope after the call.
   */
  template <class T> Local<T> Close(Handle<T> value);

  /**
   * Counts the number of allocated handles.
   */
  static int NumberOfHandles();

  /**
   * Creates a new handle with the given value.
   */
  static void** CreateHandle(void* value);

 private:
  // Make it impossible to create heap-allocated or illegal handle
  // scopes by disallowing certain operations.
  HandleScope(const HandleScope&);
  void operator=(const HandleScope&);
  void* operator new(size_t size);
  void operator delete(void*, size_t);

437 438
  // This Data class is accessible internally through a typedef in the
  // ImplementationUtilities class.
439
  class V8EXPORT Data {
440 441 442 443 444 445 446 447 448 449
   public:
    int extensions;
    void** next;
    void** limit;
    inline void Initialize() {
      extensions = -1;
      next = limit = NULL;
    }
  };

450
  Data previous_;
451

452 453
  // Allow for the active closing of HandleScopes which allows to pass a handle
  // from the HandleScope being closed to the next top most HandleScope.
454 455 456 457 458 459 460 461 462 463 464 465 466
  bool is_closed_;
  void** RawClose(void** value);

  friend class ImplementationUtilities;
};


// --- S p e c i a l   o b j e c t s ---


/**
 * The superclass of values and API object templates.
 */
467
class V8EXPORT Data {
468 469 470 471 472 473 474 475
 private:
  Data();
};


/**
 * Pre-compilation data that can be associated with a script.  This
 * data can be calculated for a script in advance of actually
476
 * compiling it, and can be stored between compilations.  When script
477
 * data is given to the compile method compilation will be faster.
478
 */
479
class V8EXPORT ScriptData {  // NOLINT
480 481 482 483 484 485 486 487 488 489 490 491 492
 public:
  virtual ~ScriptData() { }
  static ScriptData* PreCompile(const char* input, int length);
  static ScriptData* New(unsigned* data, int length);

  virtual int Length() = 0;
  virtual unsigned* Data() = 0;
};


/**
 * The origin, within a file, of a script.
 */
493
class V8EXPORT ScriptOrigin {
494
 public:
495
  ScriptOrigin(Handle<Value> resource_name,
496 497 498 499 500
               Handle<Integer> resource_line_offset = Handle<Integer>(),
               Handle<Integer> resource_column_offset = Handle<Integer>())
      : resource_name_(resource_name),
        resource_line_offset_(resource_line_offset),
        resource_column_offset_(resource_column_offset) { }
501 502 503
  inline Handle<Value> ResourceName() const;
  inline Handle<Integer> ResourceLineOffset() const;
  inline Handle<Integer> ResourceColumnOffset() const;
504
 private:
505
  Handle<Value> resource_name_;
506 507 508 509 510 511
  Handle<Integer> resource_line_offset_;
  Handle<Integer> resource_column_offset_;
};


/**
512
 * A compiled JavaScript script.
513
 */
514
class V8EXPORT Script {
515 516 517 518 519 520 521 522 523 524 525
 public:

  /**
   * Compiles the specified script. The ScriptOrigin* and ScriptData*
   * parameters are owned by the caller of Script::Compile. No
   * references to these objects are kept after compilation finishes.
   */
  static Local<Script> Compile(Handle<String> source,
                               ScriptOrigin* origin = NULL,
                               ScriptData* pre_data = NULL);

526 527 528 529 530 531 532
  /**
   * Compiles the specified script using the specified file name
   * object (typically a string) as the script's origin.
   */
  static Local<Script> Compile(Handle<String> source,
                               Handle<Value> file_name);

533 534 535
  /**
   * Runs the script returning the resulting value.
   */
536
  Local<Value> Run();
537 538 539 540 541

  /**
   * Returns the script id value.
   */
  Local<Value> Id();
542 543 544 545 546 547 548

  /**
   * Associate an additional data object with the script. This is mainly used
   * with the debugger as this data object is only available through the
   * debugger API.
   */
  void SetData(Handle<Value> data);
549 550 551 552 553 554
};


/**
 * An error message.
 */
555
class V8EXPORT Message {
556
 public:
557 558
  Local<String> Get() const;
  Local<String> GetSourceLine() const;
559

560 561 562 563
  /**
   * Returns the resource name for the script from where the function causing
   * the error originates.
   */
564
  Handle<Value> GetScriptResourceName() const;
565

566 567 568 569 570 571
  /**
   * Returns the resource data for the script from where the function causing
   * the error originates.
   */
  Handle<Value> GetScriptData() const;

572 573 574
  /**
   * Returns the number, 1-based, of the line where the error occurred.
   */
575
  int GetLineNumber() const;
576

577 578 579 580
  /**
   * Returns the index within the script of the first character where
   * the error occurred.
   */
581
  int GetStartPosition() const;
582 583 584 585 586

  /**
   * Returns the index within the script of the last character where
   * the error occurred.
   */
587
  int GetEndPosition() const;
588 589 590 591 592

  /**
   * Returns the index within the line of the first character where
   * the error occurred.
   */
593
  int GetStartColumn() const;
594 595 596 597 598

  /**
   * Returns the index within the line of the last character where
   * the error occurred.
   */
599
  int GetEndColumn() const;
600

601 602 603 604 605 606 607 608 609
  // TODO(1245381): Print to a string instead of on a FILE.
  static void PrintCurrentStackTrace(FILE* out);
};


// --- V a l u e ---


/**
610
 * The superclass of all JavaScript values and objects.
611
 */
612
class V8EXPORT Value : public Data {
613 614 615 616 617 618
 public:

  /**
   * Returns true if this value is the undefined value.  See ECMA-262
   * 4.3.10.
   */
619
  bool IsUndefined() const;
620 621 622 623 624

  /**
   * Returns true if this value is the null value.  See ECMA-262
   * 4.3.11.
   */
625
  bool IsNull() const;
626 627 628 629

   /**
   * Returns true if this value is true.
   */
630
  bool IsTrue() const;
631 632 633 634

  /**
   * Returns true if this value is false.
   */
635
  bool IsFalse() const;
636 637 638 639 640

  /**
   * Returns true if this value is an instance of the String type.
   * See ECMA-262 8.4.
   */
641
  bool IsString() const;
642 643 644 645

  /**
   * Returns true if this value is a function.
   */
646
  bool IsFunction() const;
647 648 649 650

  /**
   * Returns true if this value is an array.
   */
651
  bool IsArray() const;
652

653
  /**
654 655
   * Returns true if this value is an object.
   */
656
  bool IsObject() const;
657

658
  /**
659 660
   * Returns true if this value is boolean.
   */
661
  bool IsBoolean() const;
662

663
  /**
664 665
   * Returns true if this value is a number.
   */
666
  bool IsNumber() const;
667

668
  /**
669 670
   * Returns true if this value is external.
   */
671
  bool IsExternal() const;
672

673
  /**
674 675
   * Returns true if this value is a 32-bit signed integer.
   */
676
  bool IsInt32() const;
677

678 679 680
  /**
   * Returns true if this value is a Date.
   */
681
  bool IsDate() const;
682

683 684 685 686 687 688 689 690
  Local<Boolean> ToBoolean() const;
  Local<Number> ToNumber() const;
  Local<String> ToString() const;
  Local<String> ToDetailString() const;
  Local<Object> ToObject() const;
  Local<Integer> ToInteger() const;
  Local<Uint32> ToUint32() const;
  Local<Int32> ToInt32() const;
691 692 693 694 695

  /**
   * Attempts to convert a string to an array index.
   * Returns an empty handle if the conversion fails.
   */
696
  Local<Uint32> ToArrayIndex() const;
697

698 699 700 701 702
  bool BooleanValue() const;
  double NumberValue() const;
  int64_t IntegerValue() const;
  uint32_t Uint32Value() const;
  int32_t Int32Value() const;
703 704

  /** JS == */
705 706
  bool Equals(Handle<Value> that) const;
  bool StrictEquals(Handle<Value> that) const;
707 708 709 710 711 712
};


/**
 * The superclass of primitive values.  See ECMA-262 4.3.2.
 */
713
class V8EXPORT Primitive : public Value { };
714 715 716 717 718 719


/**
 * A primitive boolean value (ECMA-262, 4.3.14).  Either the true
 * or false value.
 */
720
class V8EXPORT Boolean : public Primitive {
721
 public:
722
  bool Value() const;
723 724 725 726 727
  static inline Handle<Boolean> New(bool value);
};


/**
728
 * A JavaScript string value (ECMA-262, 4.3.17).
729
 */
730
class V8EXPORT String : public Primitive {
731
 public:
732 733 734 735

  /**
   * Returns the number of characters in this string.
   */
736
  int Length() const;
737

738 739 740 741
  /**
   * Returns the number of bytes in the UTF-8 encoded
   * representation of this string.
   */
742
  int Utf8Length() const;
743

744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760
  /**
   * Write the contents of the string to an external buffer.
   * If no arguments are given, expects the buffer to be large
   * enough to hold the entire string and NULL terminator. Copies
   * the contents of the string and the NULL terminator into the
   * buffer.
   *
   * Copies up to length characters into the output buffer.
   * Only null-terminates if there is enough space in the buffer.
   *
   * \param buffer The buffer into which the string will be copied.
   * \param start The starting position within the string at which
   * copying begins.
   * \param length The number of bytes to copy from the string.
   * \return The number of characters copied to the buffer
   * excluding the NULL terminator.
   */
761 762 763
  int Write(uint16_t* buffer, int start = 0, int length = -1) const;  // UTF-16
  int WriteAscii(char* buffer, int start = 0, int length = -1) const;  // ASCII
  int WriteUtf8(char* buffer, int length = -1) const; // UTF-8
764

765 766 767 768 769
  /**
   * A zero length string.
   */
  static v8::Local<v8::String> Empty();

770 771 772
  /**
   * Returns true if the string is external
   */
773
  bool IsExternal() const;
774

775 776 777
  /**
   * Returns true if the string is both external and ascii
   */
778
  bool IsExternalAscii() const;
779 780 781 782
  /**
   * An ExternalStringResource is a wrapper around a two-byte string
   * buffer that resides outside V8's heap. Implement an
   * ExternalStringResource to manage the life cycle of the underlying
783
   * buffer.  Note that the string data must be immutable.
784
   */
785
  class V8EXPORT ExternalStringResource {  // NOLINT
786 787 788 789 790 791 792 793 794 795 796 797 798
   public:
    /**
     * Override the destructor to manage the life cycle of the underlying
     * buffer.
     */
    virtual ~ExternalStringResource() {}
    /** The string data from the underlying buffer.*/
    virtual const uint16_t* data() const = 0;
    /** The length of the string. That is, the number of two-byte characters.*/
    virtual size_t length() const = 0;
   protected:
    ExternalStringResource() {}
   private:
799
    // Disallow copying and assigning.
800 801 802 803 804
    ExternalStringResource(const ExternalStringResource&);
    void operator=(const ExternalStringResource&);
  };

  /**
805 806 807
   * An ExternalAsciiStringResource is a wrapper around an ascii
   * string buffer that resides outside V8's heap. Implement an
   * ExternalAsciiStringResource to manage the life cycle of the
808 809 810 811 812
   * underlying buffer.  Note that the string data must be immutable
   * and that the data must be strict 7-bit ASCII, not Latin1 or
   * UTF-8, which would require special treatment internally in the
   * engine and, in the case of UTF-8, do not allow efficient indexing.
   * Use String::New or convert to 16 bit data for non-ASCII.
813
   */
814

815
  class V8EXPORT ExternalAsciiStringResource {  // NOLINT
816 817 818 819 820 821 822 823 824 825 826 827 828
   public:
    /**
     * Override the destructor to manage the life cycle of the underlying
     * buffer.
     */
    virtual ~ExternalAsciiStringResource() {}
    /** The string data from the underlying buffer.*/
    virtual const char* data() const = 0;
    /** The number of ascii characters in the string.*/
    virtual size_t length() const = 0;
   protected:
    ExternalAsciiStringResource() {}
   private:
829
    // Disallow copying and assigning.
830 831 832 833 834
    ExternalAsciiStringResource(const ExternalAsciiStringResource&);
    void operator=(const ExternalAsciiStringResource&);
  };

  /**
835 836
   * Get the ExternalStringResource for an external string.  Returns
   * NULL if IsExternal() doesn't return true.
837
   */
838
  ExternalStringResource* GetExternalStringResource() const;
839 840 841

  /**
   * Get the ExternalAsciiStringResource for an external ascii string.
842
   * Returns NULL if IsExternalAscii() doesn't return true.
843
   */
844
  ExternalAsciiStringResource* GetExternalAsciiStringResource() const;
845 846 847 848 849 850 851 852 853 854

  static String* Cast(v8::Value* obj);

  /**
   * Allocates a new string from either utf-8 encoded or ascii data.
   * The second parameter 'length' gives the buffer length.
   * If the data is utf-8 encoded, the caller must
   * be careful to supply the length parameter.
   * If it is not given, the function calls
   * 'strlen' to determine the buffer length, it might be
855
   * wrong if 'data' contains a null character.
856 857 858 859 860 861 862 863 864
   */
  static Local<String> New(const char* data, int length = -1);

  /** Allocates a new string from utf16 data.*/
  static Local<String> New(const uint16_t* data, int length = -1);

  /** Creates a symbol. Returns one if it exists already.*/
  static Local<String> NewSymbol(const char* data, int length = -1);

865 866 867 868 869 870 871 872
  /**
   * Creates a new external string using the data defined in the given
   * resource. The resource is deleted when the external string is no
   * longer live on V8's heap. The caller of this function should not
   * delete or modify the resource. Neither should the underlying buffer be
   * deallocated or modified except through the destructor of the
   * external string resource.
   */
873
  static Local<String> NewExternal(ExternalStringResource* resource);
874

875 876 877 878 879 880 881 882 883
  /**
   * Associate an external string resource with this string by transforming it
   * in place so that existing references to this string in the JavaScript heap
   * will use the external string resource. The external string resource's
   * character contents needs to be equivalent to this string.
   * Returns true if the string has been changed to be an external string.
   * The string is not modified if the operation fails.
   */
  bool MakeExternal(ExternalStringResource* resource);
884

885 886 887 888 889 890 891 892
  /**
   * Creates a new external string using the ascii data defined in the given
   * resource. The resource is deleted when the external string is no
   * longer live on V8's heap. The caller of this function should not
   * delete or modify the resource. Neither should the underlying buffer be
   * deallocated or modified except through the destructor of the
   * external string resource.
   */
893
  static Local<String> NewExternal(ExternalAsciiStringResource* resource);
894

895 896 897 898 899 900 901 902 903
  /**
   * Associate an external string resource with this string by transforming it
   * in place so that existing references to this string in the JavaScript heap
   * will use the external string resource. The external string resource's
   * character contents needs to be equivalent to this string.
   * Returns true if the string has been changed to be an external string.
   * The string is not modified if the operation fails.
   */
  bool MakeExternal(ExternalAsciiStringResource* resource);
904

905
  /** Creates an undetectable string from the supplied ascii or utf-8 data.*/
906 907
  static Local<String> NewUndetectable(const char* data, int length = -1);

908
  /** Creates an undetectable string from the supplied utf-16 data.*/
909 910
  static Local<String> NewUndetectable(const uint16_t* data, int length = -1);

911 912
  /**
   * Converts an object to a utf8-encoded character array.  Useful if
913 914 915 916
   * you want to print the object.  If conversion to a string fails
   * (eg. due to an exception in the toString() method of the object)
   * then the length() method returns 0 and the * operator returns
   * NULL.
917
   */
918
  class V8EXPORT Utf8Value {
919 920 921
   public:
    explicit Utf8Value(Handle<v8::Value> obj);
    ~Utf8Value();
922
    char* operator*() const { return str_; }
923 924 925 926
    int length() { return length_; }
   private:
    char* str_;
    int length_;
927 928 929 930

    // Disallow copying and assigning.
    Utf8Value(const Utf8Value&);
    void operator=(const Utf8Value&);
931 932
  };

933 934 935
  /**
   * Converts an object to an ascii string.
   * Useful if you want to print the object.
936 937 938
   * If conversion to a string fails (eg. due to an exception in the toString()
   * method of the object) then the length() method returns 0 and the * operator
   * returns NULL.
939
   */
940
  class V8EXPORT AsciiValue {
941 942 943
   public:
    explicit AsciiValue(Handle<v8::Value> obj);
    ~AsciiValue();
944
    char* operator*() const { return str_; }
945
    int length() { return length_; }
946 947
   private:
    char* str_;
948
    int length_;
949 950 951 952

    // Disallow copying and assigning.
    AsciiValue(const AsciiValue&);
    void operator=(const AsciiValue&);
953 954 955 956
  };

  /**
   * Converts an object to a two-byte string.
957 958 959
   * If conversion to a string fails (eg. due to an exception in the toString()
   * method of the object) then the length() method returns 0 and the * operator
   * returns NULL.
960
   */
961
  class V8EXPORT Value {
962 963 964
   public:
    explicit Value(Handle<v8::Value> obj);
    ~Value();
965
    uint16_t* operator*() const { return str_; }
966
    int length() { return length_; }
967 968
   private:
    uint16_t* str_;
969
    int length_;
970 971 972 973

    // Disallow copying and assigning.
    Value(const Value&);
    void operator=(const Value&);
974 975 976 977 978
  };
};


/**
979
 * A JavaScript number value (ECMA-262, 4.3.20)
980
 */
981
class V8EXPORT Number : public Primitive {
982
 public:
983
  double Value() const;
984 985 986 987 988 989 990 991
  static Local<Number> New(double value);
  static Number* Cast(v8::Value* obj);
 private:
  Number();
};


/**
992
 * A JavaScript value representing a signed integer.
993
 */
994
class V8EXPORT Integer : public Number {
995 996
 public:
  static Local<Integer> New(int32_t value);
997
  int64_t Value() const;
998 999 1000 1001 1002 1003 1004
  static Integer* Cast(v8::Value* obj);
 private:
  Integer();
};


/**
1005
 * A JavaScript value representing a 32-bit signed integer.
1006
 */
1007
class V8EXPORT Int32 : public Integer {
1008
 public:
1009
  int32_t Value() const;
1010 1011 1012 1013 1014 1015
 private:
  Int32();
};


/**
1016
 * A JavaScript value representing a 32-bit unsigned integer.
1017
 */
1018
class V8EXPORT Uint32 : public Integer {
1019
 public:
1020
  uint32_t Value() const;
1021 1022 1023 1024 1025 1026 1027 1028
 private:
  Uint32();
};


/**
 * An instance of the built-in Date constructor (ECMA-262, 15.9).
 */
1029
class V8EXPORT Date : public Value {
1030 1031
 public:
  static Local<Value> New(double time);
1032 1033 1034 1035 1036

  /**
   * A specialization of Value::NumberValue that is more efficient
   * because we know the structure of this object.
   */
1037
  double NumberValue() const;
1038 1039

  static Date* Cast(v8::Value* obj);
1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050
};


enum PropertyAttribute {
  None       = 0,
  ReadOnly   = 1 << 0,
  DontEnum   = 1 << 1,
  DontDelete = 1 << 2
};

/**
1051
 * A JavaScript object (ECMA-262, 4.3.3)
1052
 */
1053
class V8EXPORT Object : public Value {
1054 1055 1056 1057
 public:
  bool Set(Handle<Value> key,
           Handle<Value> value,
           PropertyAttribute attribs = None);
christian.plesner.hansen@gmail.com's avatar
christian.plesner.hansen@gmail.com committed
1058 1059 1060 1061 1062 1063 1064

  // Sets a local property on this object, bypassing interceptors and
  // overriding accessors or read-only properties.
  //
  // Note that if the object has an interceptor the property will be set
  // locally, but since the interceptor takes precedence the local property
  // will only be returned if the interceptor doesn't return a value.
1065 1066
  //
  // Note also that this only works for named properties.
1067 1068 1069
  bool ForceSet(Handle<Value> key,
                Handle<Value> value,
                PropertyAttribute attribs = None);
1070 1071 1072 1073 1074 1075 1076 1077 1078
  Local<Value> Get(Handle<Value> key);

  // TODO(1245389): Replace the type-specific versions of these
  // functions with generic ones that accept a Handle<Value> key.
  bool Has(Handle<String> key);
  bool Delete(Handle<String> key);
  bool Has(uint32_t index);
  bool Delete(uint32_t index);

1079 1080 1081 1082 1083 1084 1085 1086
  /**
   * Returns an array containing the names of the enumerable properties
   * of this object, including properties from prototype objects.  The
   * array returned by this method contains the same values as would
   * be enumerated by a for-in statement over this object.
   */
  Local<Array> GetPropertyNames();

1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
  /**
   * Get the prototype object.  This does not skip objects marked to
   * be skipped by __proto__ and it does not consult the security
   * handler.
   */
  Local<Value> GetPrototype();

  /**
   * Call builtin Object.prototype.toString on this object.
   * This is different from Value::ToString() that may call
   * user-defined toString function. This one does not.
   */
  Local<String> ObjectProtoToString();

1101
  /** Gets the number of internal fields for this Object. */
1102
  int InternalFieldCount();
1103 1104 1105 1106
  /** Gets the value in an internal field. */
  Local<Value> GetInternalField(int index);
  /** Sets the value in an internal field. */
  void SetInternalField(int index, Handle<Value> value);
1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121

  // Testers for local properties.
  bool HasRealNamedProperty(Handle<String> key);
  bool HasRealIndexedProperty(uint32_t index);
  bool HasRealNamedCallbackProperty(Handle<String> key);

  /**
   * If result.IsEmpty() no real property was located in the prototype chain.
   * This means interceptors in the prototype chain are not called.
   */
  Handle<Value> GetRealNamedPropertyInPrototypeChain(Handle<String> key);

  /** Tests for a named lookup interceptor.*/
  bool HasNamedLookupInterceptor();

1122
  /** Tests for an index lookup interceptor.*/
1123 1124
  bool HasIndexedLookupInterceptor();

1125 1126 1127 1128
  /**
   * Turns on access check on the object if the object is an instance of
   * a template that has access check callbacks. If an object has no
   * access check info, the object cannot be accessed by anyone.
1129
   */
1130
  void TurnOnAccessCheck();
1131

1132 1133
  /**
   * Returns the identity hash for this object. The current implemenation uses
1134
   * a hidden property on the object to store the identity hash.
1135
   *
1136
   * The return value will never be 0. Also, it is not guaranteed to be
1137
   * unique.
1138 1139
   */
  int GetIdentityHash();
1140

1141 1142 1143 1144 1145 1146 1147 1148 1149
  /**
   * Access hidden properties on JavaScript objects. These properties are
   * hidden from the executing JavaScript and only accessible through the V8
   * C++ API. Hidden properties introduced by V8 internally (for example the
   * identity hash) are prefixed with "v8::".
   */
  bool SetHiddenValue(Handle<String> key, Handle<Value> value);
  Local<Value> GetHiddenValue(Handle<String> key);
  bool DeleteHiddenValue(Handle<String> key);
1150

1151 1152 1153 1154 1155 1156
  /**
   * Clone this object with a fast but shallow copy.  Values will point
   * to the same values as the original object.
   */
  Local<Object> Clone();

1157 1158 1159 1160 1161 1162 1163 1164 1165 1166
  static Local<Object> New();
  static Object* Cast(Value* obj);
 private:
  Object();
};


/**
 * An instance of the built-in array constructor (ECMA-262, 15.4.2).
 */
1167
class V8EXPORT Array : public Object {
1168
 public:
1169
  uint32_t Length() const;
1170 1171 1172 1173 1174 1175 1176 1177 1178

  static Local<Array> New(int length = 0);
  static Array* Cast(Value* obj);
 private:
  Array();
};


/**
1179
 * A JavaScript function object (ECMA-262, 15.3).
1180
 */
1181
class V8EXPORT Function : public Object {
1182
 public:
1183 1184
  Local<Object> NewInstance() const;
  Local<Object> NewInstance(int argc, Handle<Value> argv[]) const;
1185 1186
  Local<Value> Call(Handle<Object> recv, int argc, Handle<Value> argv[]);
  void SetName(Handle<String> name);
1187
  Handle<Value> GetName() const;
1188 1189 1190 1191 1192 1193 1194
  static Function* Cast(Value* obj);
 private:
  Function();
};


/**
1195 1196
 * A JavaScript value that wraps a C++ void*.  This type of value is
 * mainly used to associate C++ data structures with JavaScript
1197
 * objects.
1198 1199 1200 1201 1202 1203
 *
 * The Wrap function V8 will return the most optimal Value object wrapping the
 * C++ void*. The type of the value is not guaranteed to be an External object
 * and no assumptions about its type should be made. To access the wrapped
 * value Unwrap should be used, all other operations on that object will lead
 * to unpredictable results.
1204
 */
1205
class V8EXPORT External : public Value {
1206
 public:
1207 1208 1209
  static Local<Value> Wrap(void* data);
  static void* Unwrap(Handle<Value> obj);

1210 1211
  static Local<External> New(void* value);
  static External* Cast(Value* obj);
1212
  void* Value() const;
1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223
 private:
  External();
};


// --- T e m p l a t e s ---


/**
 * The superclass of object and function templates.
 */
1224
class V8EXPORT Template : public Data {
1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239
 public:
  /** Adds a property to each instance created by this template.*/
  void Set(Handle<String> name, Handle<Data> value,
           PropertyAttribute attributes = None);
  inline void Set(const char* name, Handle<Data> value);
 private:
  Template();

  friend class ObjectTemplate;
  friend class FunctionTemplate;
};


/**
 * The argument information given to function call callbacks.  This
1240
 * class provides access to information about the context of the call,
1241 1242 1243
 * including the receiver, the number and values of arguments, and
 * the holder of the function.
 */
1244
class V8EXPORT Arguments {
1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273
 public:
  inline int Length() const;
  inline Local<Value> operator[](int i) const;
  inline Local<Function> Callee() const;
  inline Local<Object> This() const;
  inline Local<Object> Holder() const;
  inline bool IsConstructCall() const;
  inline Local<Value> Data() const;
 private:
  Arguments();
  friend class ImplementationUtilities;
  inline Arguments(Local<Value> data,
                   Local<Object> holder,
                   Local<Function> callee,
                   bool is_construct_call,
                   void** values, int length);
  Local<Value> data_;
  Local<Object> holder_;
  Local<Function> callee_;
  bool is_construct_call_;
  void** values_;
  int length_;
};


/**
 * The information passed to an accessor callback about the context
 * of the property access.
 */
1274
class V8EXPORT AccessorInfo {
1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325
 public:
  inline AccessorInfo(Local<Object> self,
                      Local<Value> data,
                      Local<Object> holder)
      : self_(self), data_(data), holder_(holder) { }
  inline Local<Value> Data() const;
  inline Local<Object> This() const;
  inline Local<Object> Holder() const;
 private:
  Local<Object> self_;
  Local<Value> data_;
  Local<Object> holder_;
};


typedef Handle<Value> (*InvocationCallback)(const Arguments& args);

typedef int (*LookupCallback)(Local<Object> self, Local<String> name);

/**
 * Accessor[Getter|Setter] are used as callback functions when
 * setting|getting a particular property. See objectTemplate::SetAccessor.
 */
typedef Handle<Value> (*AccessorGetter)(Local<String> property,
                                        const AccessorInfo& info);


typedef void (*AccessorSetter)(Local<String> property,
                               Local<Value> value,
                               const AccessorInfo& info);


/**
 * NamedProperty[Getter|Setter] are used as interceptors on object.
 * See ObjectTemplate::SetNamedPropertyHandler.
 */
typedef Handle<Value> (*NamedPropertyGetter)(Local<String> property,
                                             const AccessorInfo& info);


/**
 * Returns the value if the setter intercepts the request.
 * Otherwise, returns an empty handle.
 */
typedef Handle<Value> (*NamedPropertySetter)(Local<String> property,
                                             Local<Value> value,
                                             const AccessorInfo& info);


/**
 * Returns a non-empty handle if the interceptor intercepts the request.
1326
 * The result is true if the property exists and false otherwise.
1327 1328 1329 1330 1331 1332 1333
 */
typedef Handle<Boolean> (*NamedPropertyQuery)(Local<String> property,
                                              const AccessorInfo& info);


/**
 * Returns a non-empty handle if the deleter intercepts the request.
1334 1335
 * The return value is true if the property could be deleted and false
 * otherwise.
1336 1337 1338 1339 1340
 */
typedef Handle<Boolean> (*NamedPropertyDeleter)(Local<String> property,
                                                const AccessorInfo& info);

/**
1341 1342
 * Returns an array containing the names of the properties the named
 * property getter intercepts.
1343 1344 1345
 */
typedef Handle<Array> (*NamedPropertyEnumerator)(const AccessorInfo& info);

1346

1347
/**
1348 1349
 * Returns the value of the property if the getter intercepts the
 * request.  Otherwise, returns an empty handle.
1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365
 */
typedef Handle<Value> (*IndexedPropertyGetter)(uint32_t index,
                                               const AccessorInfo& info);


/**
 * Returns the value if the setter intercepts the request.
 * Otherwise, returns an empty handle.
 */
typedef Handle<Value> (*IndexedPropertySetter)(uint32_t index,
                                               Local<Value> value,
                                               const AccessorInfo& info);


/**
 * Returns a non-empty handle if the interceptor intercepts the request.
1366
 * The result is true if the property exists and false otherwise.
1367 1368 1369 1370 1371 1372
 */
typedef Handle<Boolean> (*IndexedPropertyQuery)(uint32_t index,
                                                const AccessorInfo& info);

/**
 * Returns a non-empty handle if the deleter intercepts the request.
1373 1374
 * The return value is true if the property could be deleted and false
 * otherwise.
1375 1376 1377 1378
 */
typedef Handle<Boolean> (*IndexedPropertyDeleter)(uint32_t index,
                                                  const AccessorInfo& info);

1379 1380 1381 1382
/**
 * Returns an array containing the indices of the properties the
 * indexed property getter intercepts.
 */
1383 1384 1385 1386
typedef Handle<Array> (*IndexedPropertyEnumerator)(const AccessorInfo& info);


/**
1387 1388 1389 1390 1391
 * Access control specifications.
 *
 * Some accessors should be accessible across contexts.  These
 * accessors have an explicit access control parameter which specifies
 * the kind of cross-context access that should be allowed.
1392 1393 1394 1395 1396 1397
 *
 * Additionally, for security, accessors can prohibit overwriting by
 * accessors defined in JavaScript.  For objects that have such
 * accessors either locally or in their prototype chain it is not
 * possible to overwrite the accessor by using __defineGetter__ or
 * __defineSetter__ from JavaScript code.
1398 1399
 */
enum AccessControl {
1400 1401 1402 1403
  DEFAULT               = 0,
  ALL_CAN_READ          = 1,
  ALL_CAN_WRITE         = 1 << 1,
  PROHIBITS_OVERWRITING = 1 << 2
1404 1405 1406 1407
};


/**
1408
 * Access type specification.
1409 1410 1411 1412 1413 1414 1415 1416 1417
 */
enum AccessType {
  ACCESS_GET,
  ACCESS_SET,
  ACCESS_HAS,
  ACCESS_DELETE,
  ACCESS_KEYS
};

1418

1419 1420 1421 1422
/**
 * Returns true if cross-context access should be allowed to the named
 * property with the given key on the global object.
 */
1423 1424 1425 1426 1427
typedef bool (*NamedSecurityCallback)(Local<Object> global,
                                      Local<Value> key,
                                      AccessType type,
                                      Local<Value> data);

1428 1429 1430 1431 1432

/**
 * Returns true if cross-context access should be allowed to the indexed
 * property with the given index on the global object.
 */
1433 1434 1435 1436 1437 1438 1439
typedef bool (*IndexedSecurityCallback)(Local<Object> global,
                                        uint32_t index,
                                        AccessType type,
                                        Local<Value> data);


/**
1440
 * A FunctionTemplate is used to create functions at runtime. There
1441 1442
 * can only be one function created from a FunctionTemplate in a
 * context.
1443 1444
 *
 * A FunctionTemplate can have properties, these properties are added to the
1445
 * function object when it is created.
1446
 *
1447 1448 1449 1450
 * A FunctionTemplate has a corresponding instance template which is
 * used to create object instances when the function is used as a
 * constructor. Properties added to the instance template are added to
 * each object instance.
1451 1452 1453 1454
 *
 * A FunctionTemplate can have a prototype template. The prototype template
 * is used to create the prototype object of the function.
 *
1455
 * The following example shows how to use a FunctionTemplate:
1456
 *
1457
 * \code
1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471
 *    v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New();
 *    t->Set("func_property", v8::Number::New(1));
 *
 *    v8::Local<v8::Template> proto_t = t->PrototypeTemplate();
 *    proto_t->Set("proto_method", v8::FunctionTemplate::New(InvokeCallback));
 *    proto_t->Set("proto_const", v8::Number::New(2));
 *
 *    v8::Local<v8::ObjectTemplate> instance_t = t->InstanceTemplate();
 *    instance_t->SetAccessor("instance_accessor", InstanceAccessorCallback);
 *    instance_t->SetNamedPropertyHandler(PropertyHandlerCallback, ...);
 *    instance_t->Set("instance_property", Number::New(3));
 *
 *    v8::Local<v8::Function> function = t->GetFunction();
 *    v8::Local<v8::Object> instance = function->NewInstance();
1472
 * \endcode
1473 1474
 *
 * Let's use "function" as the JS variable name of the function object
1475 1476
 * and "instance" for the instance object created above.  The function
 * and the instance will have the following properties:
1477
 *
1478 1479 1480
 * \code
 *   func_property in function == true;
 *   function.func_property == 1;
1481
 *
1482 1483
 *   function.prototype.proto_method() invokes 'InvokeCallback'
 *   function.prototype.proto_const == 2;
1484
 *
1485 1486 1487 1488
 *   instance instanceof function == true;
 *   instance.instance_accessor calls 'InstanceAccessorCallback'
 *   instance.instance_property == 3;
 * \endcode
1489
 *
1490 1491 1492
 * A FunctionTemplate can inherit from another one by calling the
 * FunctionTemplate::Inherit method.  The following graph illustrates
 * the semantics of inheritance:
1493
 *
1494 1495 1496 1497 1498 1499 1500
 * \code
 *   FunctionTemplate Parent  -> Parent() . prototype -> { }
 *     ^                                                  ^
 *     | Inherit(Parent)                                  | .__proto__
 *     |                                                  |
 *   FunctionTemplate Child   -> Child()  . prototype -> { }
 * \endcode
1501
 *
1502 1503 1504 1505
 * A FunctionTemplate 'Child' inherits from 'Parent', the prototype
 * object of the Child() function has __proto__ pointing to the
 * Parent() function's prototype object. An instance of the Child
 * function has all properties on Parent's instance templates.
1506
 *
1507 1508
 * Let Parent be the FunctionTemplate initialized in the previous
 * section and create a Child FunctionTemplate by:
1509
 *
1510
 * \code
1511 1512 1513 1514 1515 1516
 *   Local<FunctionTemplate> parent = t;
 *   Local<FunctionTemplate> child = FunctionTemplate::New();
 *   child->Inherit(parent);
 *
 *   Local<Function> child_function = child->GetFunction();
 *   Local<Object> child_instance = child_function->NewInstance();
1517 1518 1519 1520
 * \endcode
 *
 * The Child function and Child instance will have the following
 * properties:
1521
 *
1522
 * \code
1523
 *   child_func.prototype.__proto__ == function.prototype;
1524
 *   child_instance.instance_accessor calls 'InstanceAccessorCallback'
1525
 *   child_instance.instance_property == 3;
1526
 * \endcode
1527
 */
1528
class V8EXPORT FunctionTemplate : public Template {
1529 1530
 public:
  /** Creates a function template.*/
1531 1532 1533 1534
  static Local<FunctionTemplate> New(
      InvocationCallback callback = 0,
      Handle<Value> data = Handle<Value>(),
      Handle<Signature> signature = Handle<Signature>());
1535 1536 1537
  /** Returns the unique function instance in the current execution context.*/
  Local<Function> GetFunction();

1538 1539 1540 1541 1542
  /**
   * Set the call-handler callback for a FunctionTemplate.  This
   * callback is called whenever the function created from this
   * FunctionTemplate is called.
   */
1543 1544 1545
  void SetCallHandler(InvocationCallback callback,
                      Handle<Value> data = Handle<Value>());

1546
  /** Get the InstanceTemplate. */
1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557
  Local<ObjectTemplate> InstanceTemplate();

  /** Causes the function template to inherit from a parent function template.*/
  void Inherit(Handle<FunctionTemplate> parent);

  /**
   * A PrototypeTemplate is the template used to create the prototype object
   * of the function created by this template.
   */
  Local<ObjectTemplate> PrototypeTemplate();

1558 1559 1560 1561 1562 1563

  /**
   * Set the class name of the FunctionTemplate.  This is used for
   * printing objects created with the function created from the
   * FunctionTemplate as its constructor.
   */
1564 1565 1566
  void SetClassName(Handle<String> name);

  /**
1567 1568 1569 1570 1571 1572 1573 1574 1575 1576
   * Determines whether the __proto__ accessor ignores instances of
   * the function template.  If instances of the function template are
   * ignored, __proto__ skips all instances and instead returns the
   * next object in the prototype chain.
   *
   * Call with a value of true to make the __proto__ accessor ignore
   * instances of the function template.  Call with a value of false
   * to make the __proto__ accessor not ignore instances of the
   * function template.  By default, instances of a function template
   * are not ignored.
1577 1578 1579 1580
   */
  void SetHiddenPrototype(bool value);

  /**
1581 1582
   * Returns true if the given object is an instance of this function
   * template.
1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614
   */
  bool HasInstance(Handle<Value> object);

 private:
  FunctionTemplate();
  void AddInstancePropertyAccessor(Handle<String> name,
                                   AccessorGetter getter,
                                   AccessorSetter setter,
                                   Handle<Value> data,
                                   AccessControl settings,
                                   PropertyAttribute attributes);
  void SetNamedInstancePropertyHandler(NamedPropertyGetter getter,
                                       NamedPropertySetter setter,
                                       NamedPropertyQuery query,
                                       NamedPropertyDeleter remover,
                                       NamedPropertyEnumerator enumerator,
                                       Handle<Value> data);
  void SetIndexedInstancePropertyHandler(IndexedPropertyGetter getter,
                                         IndexedPropertySetter setter,
                                         IndexedPropertyQuery query,
                                         IndexedPropertyDeleter remover,
                                         IndexedPropertyEnumerator enumerator,
                                         Handle<Value> data);
  void SetInstanceCallAsFunctionHandler(InvocationCallback callback,
                                        Handle<Value> data);

  friend class Context;
  friend class ObjectTemplate;
};


/**
1615 1616 1617 1618
 * An ObjectTemplate is used to create objects at runtime.
 *
 * Properties added to an ObjectTemplate are added to each object
 * created from the ObjectTemplate.
1619
 */
1620
class V8EXPORT ObjectTemplate : public Template {
1621
 public:
1622
  /** Creates an ObjectTemplate. */
1623
  static Local<ObjectTemplate> New();
1624

1625 1626 1627 1628 1629
  /** Creates a new instance of this template.*/
  Local<Object> NewInstance();

  /**
   * Sets an accessor on the object template.
1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643
   *
   * Whenever the property with the given name is accessed on objects
   * created from this ObjectTemplate the getter and setter callbacks
   * are called instead of getting and setting the property directly
   * on the JavaScript object.
   *
   * \param name The name of the property for which an accessor is added.
   * \param getter The callback to invoke when getting the property.
   * \param setter The callback to invoke when setting the property.
   * \param data A piece of data that will be passed to the getter and setter
   *   callbacks whenever they are invoked.
   * \param settings Access control settings for the accessor. This is a bit
   *   field consisting of one of more of
   *   DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
1644 1645 1646
   *   The default is to not allow cross-context access.
   *   ALL_CAN_READ means that all cross-context reads are allowed.
   *   ALL_CAN_WRITE means that all cross-context writes are allowed.
1647
   *   The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
1648
   *   cross-context access.
1649 1650
   * \param attribute The attributes of the property for which an accessor
   *   is added.
1651 1652 1653 1654 1655 1656 1657 1658 1659 1660
   */
  void SetAccessor(Handle<String> name,
                   AccessorGetter getter,
                   AccessorSetter setter = 0,
                   Handle<Value> data = Handle<Value>(),
                   AccessControl settings = DEFAULT,
                   PropertyAttribute attribute = None);

  /**
   * Sets a named property handler on the object template.
1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673
   *
   * Whenever a named property is accessed on objects created from
   * this object template, the provided callback is invoked instead of
   * accessing the property directly on the JavaScript object.
   *
   * \param getter The callback to invoke when getting a property.
   * \param setter The callback to invoke when setting a property.
   * \param query The callback to invoke to check is an object has a property.
   * \param deleter The callback to invoke when deleting a property.
   * \param enumerator The callback to invoke to enumerate all the named
   *   properties of an object.
   * \param data A piece of data that will be passed to the callbacks
   *   whenever they are invoked.
1674 1675 1676 1677 1678 1679 1680 1681 1682 1683
   */
  void SetNamedPropertyHandler(NamedPropertyGetter getter,
                               NamedPropertySetter setter = 0,
                               NamedPropertyQuery query = 0,
                               NamedPropertyDeleter deleter = 0,
                               NamedPropertyEnumerator enumerator = 0,
                               Handle<Value> data = Handle<Value>());

  /**
   * Sets an indexed property handler on the object template.
1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696
   *
   * Whenever an indexed property is accessed on objects created from
   * this object template, the provided callback is invoked instead of
   * accessing the property directly on the JavaScript object.
   *
   * \param getter The callback to invoke when getting a property.
   * \param setter The callback to invoke when setting a property.
   * \param query The callback to invoke to check is an object has a property.
   * \param deleter The callback to invoke when deleting a property.
   * \param enumerator The callback to invoke to enumerate all the indexed
   *   properties of an object.
   * \param data A piece of data that will be passed to the callbacks
   *   whenever they are invoked.
1697 1698 1699 1700 1701 1702 1703 1704 1705 1706
   */
  void SetIndexedPropertyHandler(IndexedPropertyGetter getter,
                                 IndexedPropertySetter setter = 0,
                                 IndexedPropertyQuery query = 0,
                                 IndexedPropertyDeleter deleter = 0,
                                 IndexedPropertyEnumerator enumerator = 0,
                                 Handle<Value> data = Handle<Value>());
  /**
   * Sets the callback to be used when calling instances created from
   * this template as a function.  If no callback is set, instances
1707
   * behave like normal JavaScript objects that cannot be called as a
1708 1709 1710 1711 1712
   * function.
   */
  void SetCallAsFunctionHandler(InvocationCallback callback,
                                Handle<Value> data = Handle<Value>());

1713 1714 1715 1716 1717 1718 1719 1720
  /**
   * Mark object instances of the template as undetectable.
   *
   * In many ways, undetectable objects behave as though they are not
   * there.  They behave like 'undefined' in conditionals and when
   * printed.  However, properties can be accessed and called as on
   * normal objects.
   */
1721 1722
  void MarkAsUndetectable();

1723 1724 1725 1726 1727
  /**
   * Sets access check callbacks on the object template.
   *
   * When accessing properties on instances of this object template,
   * the access check callback will be called to determine whether or
1728
   * not to allow cross-context access to the properties.
1729 1730 1731 1732
   * The last parameter specifies whether access checks are turned
   * on by default on instances. If access checks are off by default,
   * they can be turned on on individual instances by calling
   * Object::TurnOnAccessCheck().
1733
   */
1734 1735
  void SetAccessCheckCallbacks(NamedSecurityCallback named_handler,
                               IndexedSecurityCallback indexed_handler,
1736 1737
                               Handle<Value> data = Handle<Value>(),
                               bool turned_on_by_default = true);
1738

1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750
  /**
   * Gets the number of internal fields for objects generated from
   * this template.
   */
  int InternalFieldCount();

  /**
   * Sets the number of internal fields for objects generated from
   * this template.
   */
  void SetInternalFieldCount(int value);

1751 1752 1753 1754 1755 1756 1757 1758
 private:
  ObjectTemplate();
  static Local<ObjectTemplate> New(Handle<FunctionTemplate> constructor);
  friend class FunctionTemplate;
};


/**
1759 1760
 * A Signature specifies which receivers and arguments a function can
 * legally be called with.
1761
 */
1762
class V8EXPORT Signature : public Data {
1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773
 public:
  static Local<Signature> New(Handle<FunctionTemplate> receiver =
                                  Handle<FunctionTemplate>(),
                              int argc = 0,
                              Handle<FunctionTemplate> argv[] = 0);
 private:
  Signature();
};


/**
1774 1775
 * A utility for determining the type of objects based on the template
 * they were constructed from.
1776
 */
1777
class V8EXPORT TypeSwitch : public Data {
1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792
 public:
  static Local<TypeSwitch> New(Handle<FunctionTemplate> type);
  static Local<TypeSwitch> New(int argc, Handle<FunctionTemplate> types[]);
  int match(Handle<Value> value);
 private:
  TypeSwitch();
};


// --- E x t e n s i o n s ---


/**
 * Ignore
 */
1793
class V8EXPORT Extension {  // NOLINT
1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817
 public:
  Extension(const char* name,
            const char* source = 0,
            int dep_count = 0,
            const char** deps = 0);
  virtual ~Extension() { }
  virtual v8::Handle<v8::FunctionTemplate>
      GetNativeFunction(v8::Handle<v8::String> name) {
    return v8::Handle<v8::FunctionTemplate>();
  }

  const char* name() { return name_; }
  const char* source() { return source_; }
  int dependency_count() { return dep_count_; }
  const char** dependencies() { return deps_; }
  void set_auto_enable(bool value) { auto_enable_ = value; }
  bool auto_enable() { return auto_enable_; }

 private:
  const char* name_;
  const char* source_;
  int dep_count_;
  const char** deps_;
  bool auto_enable_;
1818 1819 1820 1821

  // Disallow copying and assigning.
  Extension(const Extension&);
  void operator=(const Extension&);
1822 1823 1824
};


1825
void V8EXPORT RegisterExtension(Extension* extension);
1826 1827 1828 1829 1830


/**
 * Ignore
 */
1831
class V8EXPORT DeclareExtension {
1832 1833 1834 1835 1836 1837 1838 1839 1840 1841
 public:
  inline DeclareExtension(Extension* extension) {
    RegisterExtension(extension);
  }
};


// --- S t a t i c s ---


1842 1843 1844 1845
Handle<Primitive> V8EXPORT Undefined();
Handle<Primitive> V8EXPORT Null();
Handle<Boolean> V8EXPORT True();
Handle<Boolean> V8EXPORT False();
1846 1847 1848 1849 1850 1851


/**
 * A set of constraints that specifies the limits of the runtime's
 * memory use.
 */
1852
class V8EXPORT ResourceConstraints {
1853 1854
 public:
  ResourceConstraints();
1855
  int max_young_space_size() const { return max_young_space_size_; }
1856
  void set_max_young_space_size(int value) { max_young_space_size_ = value; }
1857
  int max_old_space_size() const { return max_old_space_size_; }
1858
  void set_max_old_space_size(int value) { max_old_space_size_ = value; }
1859
  uint32_t* stack_limit() const { return stack_limit_; }
1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880
  void set_stack_limit(uint32_t* value) { stack_limit_ = value; }
 private:
  int max_young_space_size_;
  int max_old_space_size_;
  uint32_t* stack_limit_;
};


bool SetResourceConstraints(ResourceConstraints* constraints);


// --- E x c e p t i o n s ---


typedef void (*FatalErrorCallback)(const char* location, const char* message);


typedef void (*MessageCallback)(Handle<Message> message, Handle<Value> data);


/**
1881 1882
 * Schedules an exception to be thrown when returning to JavaScript.  When an
 * exception has been scheduled it is illegal to invoke any JavaScript
1883
 * operation; the caller must return immediately and only after the exception
1884
 * has been handled does it become legal to invoke JavaScript operations.
1885
 */
1886
Handle<Value> V8EXPORT ThrowException(Handle<Value> exception);
1887 1888 1889 1890 1891

/**
 * Create new error objects by calling the corresponding error object
 * constructor with the message.
 */
1892
class V8EXPORT Exception {
1893 1894 1895 1896 1897 1898 1899 1900 1901
 public:
  static Local<Value> RangeError(Handle<String> message);
  static Local<Value> ReferenceError(Handle<String> message);
  static Local<Value> SyntaxError(Handle<String> message);
  static Local<Value> TypeError(Handle<String> message);
  static Local<Value> Error(Handle<String> message);
};


1902
// --- C o u n t e r s  C a l l b a c k s ---
1903

1904
typedef int* (*CounterLookupCallback)(const char* name);
1905

1906 1907 1908 1909 1910 1911 1912
typedef void* (*CreateHistogramCallback)(const char* name,
                                         int min,
                                         int max,
                                         size_t buckets);

typedef void (*AddHistogramSampleCallback)(void* histogram, int sample);

1913 1914 1915 1916 1917 1918 1919 1920 1921
// --- 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 ---
typedef void (*FailedAccessCheckCallback)(Local<Object> target,
                                          AccessType type,
                                          Local<Value> data);

// --- 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

/**
 * Applications can register a callback function which is called
1922 1923 1924 1925
 * before and after a major garbage collection.  Allocations are not
 * allowed in the callback function, you therefore cannot manipulate
 * objects (set or delete properties for example) since it is possible
 * such operations will result in the allocation of objects.
1926 1927 1928 1929
 */
typedef void (*GCCallback)();


1930
// --- C o n t e x t  G e n e r a t o r ---
1931 1932 1933

/**
 * Applications must provide a callback function which is called to generate
1934
 * a context if a context was not deserialized from the snapshot.
1935 1936 1937 1938 1939 1940 1941
 */
typedef Persistent<Context> (*ContextGenerator)();


/**
 * Container class for static utility functions.
 */
1942
class V8EXPORT V8 {
1943
 public:
1944
  /** Set the callback to invoke in case of fatal errors. */
1945 1946
  static void SetFatalErrorHandler(FatalErrorCallback that);

1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958
  /**
   * Ignore out-of-memory exceptions.
   *
   * V8 running out of memory is treated as a fatal error by default.
   * This means that the fatal error handler is called and that V8 is
   * terminated.
   *
   * IgnoreOutOfMemoryException can be used to not treat a
   * out-of-memory situation as a fatal error.  This way, the contexts
   * that did not cause the out of memory problem might be able to
   * continue execution.
   */
1959 1960
  static void IgnoreOutOfMemoryException();

1961
  /**
1962
   * Check if V8 is dead and therefore unusable.  This is the case after
1963 1964
   * fatal errors such as out-of-memory situations.
   */
1965 1966 1967
  static bool IsDead();

  /**
1968 1969 1970 1971
   * Adds a message listener.
   *
   * The same message listener can be added more than once and it that
   * case it will be called more than once for each message.
1972 1973 1974 1975 1976 1977 1978 1979 1980 1981
   */
  static bool AddMessageListener(MessageCallback that,
                                 Handle<Value> data = Handle<Value>());

  /**
   * Remove all message listeners from the specified callback function.
   */
  static void RemoveMessageListeners(MessageCallback that);

  /**
1982
   * Sets V8 flags from a string.
1983 1984 1985
   */
  static void SetFlagsFromString(const char* str, int length);

1986
  /**
1987
   * Sets V8 flags from the command line.
1988 1989 1990 1991 1992
   */
  static void SetFlagsFromCommandLine(int* argc,
                                      char** argv,
                                      bool remove_flags);

1993 1994
  /** Get the version string. */
  static const char* GetVersion();
1995 1996 1997 1998 1999 2000

  /**
   * Enables the host application to provide a mechanism for recording
   * statistics counters.
   */
  static void SetCounterFunction(CounterLookupCallback);
2001 2002 2003 2004 2005 2006 2007 2008 2009

  /**
   * Enables the host application to provide a mechanism for recording
   * histograms. The CreateHistogram function returns a
   * histogram which will later be passed to the AddHistogramSample
   * function.
   */
  static void SetCreateHistogramFunction(CreateHistogramCallback);
  static void SetAddHistogramSampleFunction(AddHistogramSampleCallback);
2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020

  /**
   * Enables the computation of a sliding window of states. The sliding
   * window information is recorded in statistics counters.
   */
  static void EnableSlidingStateWindow();

  /** Callback function for reporting failed access checks.*/
  static void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback);

  /**
2021
   * Enables the host application to receive a notification before a
mads.s.ager's avatar
mads.s.ager committed
2022 2023 2024 2025
   * major garbage colletion.  Allocations are not allowed in the
   * callback function, you therefore cannot manipulate objects (set
   * or delete properties for example) since it is possible such
   * operations will result in the allocation of objects.
2026 2027 2028 2029
   */
  static void SetGlobalGCPrologueCallback(GCCallback);

  /**
2030
   * Enables the host application to receive a notification after a
mads.s.ager's avatar
mads.s.ager committed
2031 2032 2033 2034
   * major garbage collection.  Allocations are not allowed in the
   * callback function, you therefore cannot manipulate objects (set
   * or delete properties for example) since it is possible such
   * operations will result in the allocation of objects.
2035 2036 2037 2038
   */
  static void SetGlobalGCEpilogueCallback(GCCallback);

  /**
2039 2040
   * Allows the host application to group objects together. If one
   * object in the group is alive, all objects in the group are alive.
mads.s.ager's avatar
mads.s.ager committed
2041 2042
   * After each garbage collection, object groups are removed. It is
   * intended to be used in the before-garbage-collection callback
2043
   * function, for instance to simulate DOM tree connections among JS
mads.s.ager's avatar
mads.s.ager committed
2044
   * wrapper objects.
2045
   */
2046
  static void AddObjectGroup(Persistent<Value>* objects, size_t length);
2047 2048

  /**
2049 2050
   * Initializes from snapshot if possible. Otherwise, attempts to
   * initialize from scratch.
2051 2052 2053
   */
  static bool Initialize();

2054
  /**
2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066
   * Adjusts the amount of registered external memory.  Used to give
   * V8 an indication of the amount of externally allocated memory
   * that is kept alive by JavaScript objects.  V8 uses this to decide
   * when to perform global garbage collections.  Registering
   * externally allocated memory will trigger global garbage
   * collections more often than otherwise in an attempt to garbage
   * collect the JavaScript objects keeping the externally allocated
   * memory alive.
   *
   * \param change_in_bytes the change in externally allocated memory
   *   that is kept alive by JavaScript objects.
   * \returns the adjusted value.
2067 2068 2069
   */
  static int AdjustAmountOfExternalAllocatedMemory(int change_in_bytes);

2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086
  /**
   * Suspends recording of tick samples in the profiler.
   * When the V8 profiling mode is enabled (usually via command line
   * switches) this function suspends recording of tick samples.
   * Profiling ticks are discarded until ResumeProfiler() is called.
   *
   * See also the --prof and --prof_auto command line switches to
   * enable V8 profiling.
   */
  static void PauseProfiler();

  /**
   * Resumes recording of tick samples in the profiler.
   * See also PauseProfiler().
   */
  static void ResumeProfiler();

2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104
  /**
   * If logging is performed into a memory buffer (via --logfile=*), allows to
   * retrieve previously written messages. This can be used for retrieving
   * profiler log data in the application. This function is thread-safe.
   *
   * Caller provides a destination buffer that must exist during GetLogLines
   * call. Only whole log lines are copied into the buffer.
   *
   * \param from_pos specified a point in a buffer to read from, 0 is the
   *   beginning of a buffer. It is assumed that caller updates its current
   *   position using returned size value from the previous call.
   * \param dest_buf destination buffer for log data.
   * \param max_size size of the destination buffer.
   * \returns actual size of log data copied into buffer.
   */
  static int GetLogLines(int from_pos, char* dest_buf, int max_size);


2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115
  /**
   * Releases any resources used by v8 and stops any utility threads
   * that may be running.  Note that disposing v8 is permanent, it
   * cannot be reinitialized.
   *
   * It should generally not be necessary to dispose v8 before exiting
   * a process, this should happen automatically.  It is only necessary
   * to use if the process needs the resources taken up by v8.
   */
  static bool Dispose();

2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135
 private:
  V8();

  static void** GlobalizeReference(void** handle);
  static void DisposeGlobal(void** global_handle);
  static void MakeWeak(void** global_handle, void* data, WeakReferenceCallback);
  static void ClearWeak(void** global_handle);
  static bool IsGlobalNearDeath(void** global_handle);
  static bool IsGlobalWeak(void** global_handle);

  template <class T> friend class Handle;
  template <class T> friend class Local;
  template <class T> friend class Persistent;
  friend class Context;
};


/**
 * An external exception handler.
 */
2136
class V8EXPORT TryCatch {
2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151
 public:

  /**
   * Creates a new try/catch block and registers it with v8.
   */
  TryCatch();

  /**
   * Unregisters and deletes this try/catch block.
   */
  ~TryCatch();

  /**
   * Returns true if an exception has been caught by this try/catch block.
   */
2152
  bool HasCaught() const;
2153 2154 2155 2156 2157 2158 2159

  /**
   * Returns the exception caught by this try/catch block.  If no exception has
   * been caught an empty handle is returned.
   *
   * The returned handle is valid until this TryCatch block has been destroyed.
   */
2160
  Local<Value> Exception() const;
2161

2162 2163 2164 2165 2166 2167 2168
  /**
   * Returns the message associated with this exception.  If there is
   * no message associated an empty handle is returned.
   *
   * The returned handle is valid until this TryCatch block has been
   * destroyed.
   */
2169
  Local<v8::Message> Message() const;
2170

2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181
  /**
   * Clears any exceptions that may have been caught by this try/catch block.
   * After this method has been called, HasCaught() will return false.
   *
   * It is not necessary to clear a try/catch block before using it again; if
   * another exception is thrown the previously caught exception will just be
   * overwritten.  However, it is often a good idea since it makes it easier
   * to determine which operation threw a given exception.
   */
  void Reset();

2182 2183 2184 2185 2186 2187 2188 2189
  /**
   * Set verbosity of the external exception handler.
   *
   * By default, exceptions that are caught by an external exception
   * handler are not reported.  Call SetVerbose with true on an
   * external exception handler to have exceptions caught by the
   * handler reported as if they were not caught.
   */
2190 2191
  void SetVerbose(bool value);

2192 2193 2194 2195 2196 2197 2198
  /**
   * Set whether or not this TryCatch should capture a Message object
   * which holds source information about where the exception
   * occurred.  True by default.
   */
  void SetCaptureMessage(bool value);

2199 2200 2201
 public:
  TryCatch* next_;
  void* exception_;
2202
  void* message_;
2203
  bool is_verbose_;
2204
  bool capture_message_;
2205
  void* js_handler_;
2206 2207 2208 2209 2210 2211 2212 2213 2214
};


// --- C o n t e x t ---


/**
 * Ignore
 */
2215
class V8EXPORT ExtensionConfiguration {
2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229
 public:
  ExtensionConfiguration(int name_count, const char* names[])
      : name_count_(name_count), names_(names) { }
 private:
  friend class ImplementationUtilities;
  int name_count_;
  const char** names_;
};


/**
 * A sandboxed execution context with its own set of built-in objects
 * and functions.
 */
2230
class V8EXPORT Context {
2231
 public:
2232
  /** Returns the global object of the context. */
2233 2234
  Local<Object> Global();

2235 2236 2237 2238 2239 2240
  /**
   * Detaches the global object from its context before
   * the global object can be reused to create a new context.
   */
  void DetachGlobal();

2241 2242 2243 2244 2245
  /** Creates a new context. */
  static Persistent<Context> New(
      ExtensionConfiguration* extensions = 0,
      Handle<ObjectTemplate> global_template = Handle<ObjectTemplate>(),
      Handle<Value> global_object = Handle<Value>());
2246

2247 2248
  /** Returns the last entered context. */
  static Local<Context> GetEntered();
2249

2250 2251 2252
  /** Returns the context that is on the top of the stack. */
  static Local<Context> GetCurrent();

2253 2254 2255 2256 2257 2258 2259
  /**
   * Returns the context of the calling JavaScript code.  That is the
   * context of the top-most JavaScript frame.  If there are no
   * JavaScript frames an empty handle is returned.
   */
  static Local<Context> GetCalling();

2260 2261 2262 2263 2264 2265
  /**
   * Sets the security token for the context.  To access an object in
   * another context, the security tokens must match.
   */
  void SetSecurityToken(Handle<Value> token);

2266 2267 2268
  /** Restores the security token to the default value. */
  void UseDefaultSecurityToken();

2269 2270 2271
  /** Returns the security token of this context.*/
  Handle<Value> GetSecurityToken();

2272 2273 2274 2275 2276 2277
  /**
   * Enter this context.  After entering a context, all code compiled
   * and run is compiled and run in this context.  If another context
   * is already entered, this old context is saved so it can be
   * restored when the new context is exited.
   */
2278
  void Enter();
2279 2280 2281 2282 2283

  /**
   * Exit this context.  Exiting the current context restores the
   * context that was in place when entering the current context.
   */
2284 2285
  void Exit();

2286
  /** Returns true if the context has experienced an out of memory situation. */
2287 2288
  bool HasOutOfMemoryException();

2289
  /** Returns true if V8 has a current context. */
2290 2291
  static bool InContext();

2292 2293 2294 2295 2296 2297 2298 2299
  /**
   * Associate an additional data object with the context. This is mainly used
   * with the debugger to provide additional information on the context through
   * the debugger API.
   */
  void SetData(Handle<Value> data);
  Local<Value> GetData();

2300 2301 2302 2303
  /**
   * Stack-allocated class which sets the execution context for all
   * operations executed within a local scope.
   */
2304
  class V8EXPORT Scope {
2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322
   public:
    inline Scope(Handle<Context> context) : context_(context) {
      context_->Enter();
    }
    inline ~Scope() { context_->Exit(); }
   private:
    Handle<Context> context_;
  };

 private:
  friend class Value;
  friend class Script;
  friend class Object;
  friend class Function;
};


/**
2323 2324 2325 2326 2327
 * Multiple threads in V8 are allowed, but only one thread at a time
 * is allowed to use V8.  The definition of 'using V8' includes
 * accessing handles or holding onto object pointers obtained from V8
 * handles.  It is up to the user of V8 to ensure (perhaps with
 * locking) that this constraint is not violated.
2328 2329 2330 2331 2332 2333
 *
 * If you wish to start using V8 in a thread you can do this by constructing
 * a v8::Locker object.  After the code using V8 has completed for the
 * current thread you can call the destructor.  This can be combined
 * with C++ scope-based construction as follows:
 *
2334
 * \code
2335 2336 2337 2338 2339 2340 2341
 * ...
 * {
 *   v8::Locker locker;
 *   ...
 *   // Code using V8 goes here.
 *   ...
 * } // Destructor called here
2342
 * \endcode
2343 2344 2345 2346 2347
 *
 * If you wish to stop using V8 in a thread A you can do this by either
 * by destroying the v8::Locker object as above or by constructing a
 * v8::Unlocker object:
 *
2348
 * \code
2349 2350 2351 2352 2353 2354
 * {
 *   v8::Unlocker unlocker;
 *   ...
 *   // Code not using V8 goes here while V8 can run in another thread.
 *   ...
 * } // Destructor called here.
2355
 * \endcode
2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370
 *
 * The Unlocker object is intended for use in a long-running callback
 * from V8, where you want to release the V8 lock for other threads to
 * use.
 *
 * The v8::Locker is a recursive lock.  That is, you can lock more than
 * once in a given thread.  This can be useful if you have code that can
 * be called either from code that holds the lock or from code that does
 * not.  The Unlocker is not recursive so you can not have several
 * Unlockers on the stack at once, and you can not use an Unlocker in a
 * thread that is not inside a Locker's scope.
 *
 * An unlocker will unlock several lockers if it has to and reinstate
 * the correct depth of locking on its destruction. eg.:
 *
2371
 * \code
2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387
 * // V8 not locked.
 * {
 *   v8::Locker locker;
 *   // V8 locked.
 *   {
 *     v8::Locker another_locker;
 *     // V8 still locked (2 levels).
 *     {
 *       v8::Unlocker unlocker;
 *       // V8 not locked.
 *     }
 *     // V8 locked again (2 levels).
 *   }
 *   // V8 still locked (1 level).
 * }
 * // V8 Now no longer locked.
2388
 * \endcode
2389
 */
2390
class V8EXPORT Unlocker {
2391 2392 2393 2394 2395 2396
 public:
  Unlocker();
  ~Unlocker();
};


2397
class V8EXPORT Locker {
2398 2399 2400
 public:
  Locker();
  ~Locker();
2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415

  /**
   * Start preemption.
   *
   * When preemption is started, a timer is fired every n milli seconds
   * that will switch between multiple threads that are in contention
   * for the V8 lock.
   */
  static void StartPreemption(int every_n_ms);

  /**
   * Stop preemption.
   */
  static void StopPreemption();

2416 2417 2418 2419 2420
  /**
   * Returns whether or not the locker is locked by the current thread.
   */
  static bool IsLocked();

2421 2422 2423 2424 2425
  /**
   * Returns whether v8::Locker is being used by this V8 instance.
   */
  static bool IsActive() { return active_; }

2426 2427 2428
 private:
  bool has_lock_;
  bool top_level_;
2429

2430 2431
  static bool active_;

2432 2433 2434
  // Disallow copying and assigning.
  Locker(const Locker&);
  void operator=(const Locker&);
2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465
};



// --- I m p l e m e n t a t i o n ---

template <class T>
Handle<T>::Handle() : val_(0) { }


template <class T>
Local<T>::Local() : Handle<T>() { }


template <class T>
Local<T> Local<T>::New(Handle<T> that) {
  if (that.IsEmpty()) return Local<T>();
  void** p = reinterpret_cast<void**>(*that);
  return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(*p)));
}


template <class T>
Persistent<T> Persistent<T>::New(Handle<T> that) {
  if (that.IsEmpty()) return Persistent<T>();
  void** p = reinterpret_cast<void**>(*that);
  return Persistent<T>(reinterpret_cast<T*>(V8::GlobalizeReference(p)));
}


template <class T>
2466
bool Persistent<T>::IsNearDeath() const {
2467 2468 2469 2470 2471 2472
  if (this->IsEmpty()) return false;
  return V8::IsGlobalNearDeath(reinterpret_cast<void**>(**this));
}


template <class T>
2473
bool Persistent<T>::IsWeak() const {
2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499
  if (this->IsEmpty()) return false;
  return V8::IsGlobalWeak(reinterpret_cast<void**>(**this));
}


template <class T>
void Persistent<T>::Dispose() {
  if (this->IsEmpty()) return;
  V8::DisposeGlobal(reinterpret_cast<void**>(**this));
}


template <class T>
Persistent<T>::Persistent() : Handle<T>() { }

template <class T>
void Persistent<T>::MakeWeak(void* parameters, WeakReferenceCallback callback) {
  V8::MakeWeak(reinterpret_cast<void**>(**this), parameters, callback);
}

template <class T>
void Persistent<T>::ClearWeak() {
  V8::ClearWeak(reinterpret_cast<void**>(**this));
}

template <class T>
2500
T* Handle<T>::operator->() const {
2501 2502 2503 2504 2505
  return val_;
}


template <class T>
2506
T* Handle<T>::operator*() const {
2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567
  return val_;
}


Local<Value> Arguments::operator[](int i) const {
  if (i < 0 || length_ <= i) return Local<Value>(*Undefined());
  return Local<Value>(reinterpret_cast<Value*>(values_ - i));
}


Local<Function> Arguments::Callee() const {
  return callee_;
}


Local<Object> Arguments::This() const {
  return Local<Object>(reinterpret_cast<Object*>(values_ + 1));
}


Local<Object> Arguments::Holder() const {
  return holder_;
}


Local<Value> Arguments::Data() const {
  return data_;
}


bool Arguments::IsConstructCall() const {
  return is_construct_call_;
}


int Arguments::Length() const {
  return length_;
}


Local<Value> AccessorInfo::Data() const {
  return data_;
}


Local<Object> AccessorInfo::This() const {
  return self_;
}


Local<Object> AccessorInfo::Holder() const {
  return holder_;
}


template <class T>
Local<T> HandleScope::Close(Handle<T> value) {
  void** after = RawClose(reinterpret_cast<void**>(*value));
  return Local<T>(reinterpret_cast<T*>(after));
}

2568
Handle<Value> ScriptOrigin::ResourceName() const {
2569 2570 2571 2572
  return resource_name_;
}


2573
Handle<Integer> ScriptOrigin::ResourceLineOffset() const {
2574 2575 2576 2577
  return resource_line_offset_;
}


2578
Handle<Integer> ScriptOrigin::ResourceColumnOffset() const {
2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593
  return resource_column_offset_;
}


Handle<Boolean> Boolean::New(bool value) {
  return value ? True() : False();
}


void Template::Set(const char* name, v8::Handle<Data> value) {
  Set(v8::String::New(name), value);
}


/**
2594 2595
 * \example shell.cc
 * A simple shell that takes a list of expressions on the
2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607
 * command-line and executes them.
 */


/**
 * \example process.cc
 */


}  // namespace v8


2608 2609
#undef V8EXPORT
#undef V8EXPORT_INLINE
2610 2611 2612
#undef TYPE_CHECK


2613
#endif  // V8_H_