Heavy cleanup of the external pointer API.

include/v8.h

 // Copyright 2012 the V8 project authors. All rights reserved.
 // 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
@@ skipping 58 matching lines @@
 #define V8EXPORT __attribute__ ((visibility("default")))
 #else
 #define V8EXPORT
 #endif
 #else
 #define V8EXPORT
 #endif
 
 #endif  // _WIN32
 
+// TODO(svenpanne) Remove this when the Chrome's v8 bindings have been adapted.
+#define V8_DISABLE_DEPRECATIONS 1
+
+#if defined(__GNUC__) && !defined(V8_DISABLE_DEPRECATIONS)
+#define V8_DEPRECATED(func) func __attribute__ ((deprecated))
+#elif defined(_MSC_VER) && !defined(V8_DISABLE_DEPRECATIONS)
+#define V8_DEPRECATED(func) __declspec(deprecated) func
+#else
+#define V8_DEPRECATED(func) func
+#endif
+
 /**
  * The v8 JavaScript engine.
  */
 namespace v8 {
 
 class Context;
 class String;
 class StringObject;
 class Value;
 class Utils;
@@ skipping 1491 matching lines @@
    */
   V8EXPORT Local<Value> GetConstructor();
 
   /**
    * Returns the name of the function invoked as a constructor for this object.
    */
   V8EXPORT Local<String> GetConstructorName();
 
   /** Gets the number of internal fields for this Object. */
   V8EXPORT int InternalFieldCount();
-  /** Gets the value in an internal field. */
+
+  /** Gets the value from an internal field. */
   inline Local<Value> GetInternalField(int index);
+
   /** Sets the value in an internal field. */
   V8EXPORT void SetInternalField(int index, Handle<Value> value);
 
-  /** Gets a native pointer from an internal field. */
-  inline void* GetPointerFromInternalField(int index);
+  /**
+   * Gets a native pointer from an internal field. Deprecated. If your pointer
+   * is always 2-byte-aligned, use GetAlignedPointerFromInternalField instead,
+   * otherwise use a combination of GetInternalField, External::Cast and
+   * External::Value.
+   */
+  V8_DEPRECATED(void* GetPointerFromInternalField(int index));
 
-  /** Sets a native pointer in an internal field. */
-  V8EXPORT void SetPointerInInternalField(int index, void* value);
+  /**
+   * Sets a native pointer in an internal field. Deprecated. If your pointer is
+   * always 2-byte aligned, use SetAlignedPointerInInternalField instead,
+   * otherwise use a combination of External::New and SetInternalField.
+   */
+  inline V8_DEPRECATED(void SetPointerInInternalField(int index, void* value));
+
+  /**
+   * Gets a 2-byte-aligned native pointer from an internal field. This field
+   * must have been set by SetAlignedPointerInInternalField, everything else
+   * leads to undefined behavior.
+   */
+  inline void* GetAlignedPointerFromInternalField(int index);
+
+  /**
+   * Sets a 2-byte-aligned native pointer in an internal field. To retrieve such
+   * a field, you must use GetAlignedPointerFromInternalField, everything else

[Michael Starzinger, 2012/10/25 09:41:53]

Can we rephrase the comment so that it doesn't use personal pronouns. E.g. "Such
a field must be retrieved via GetAlignedPointerFromInternalField, everything
else [...]"

[Sven Panne, 2012/10/25 14:23:08]

Done here and at similar places.

+   * leads to undefined behavior.
+   */
+  V8EXPORT void SetAlignedPointerInInternalField(int index, void* value);
 
   // Testers for local properties.
   V8EXPORT bool HasOwnProperty(Handle<String> key);
   V8EXPORT bool HasRealNamedProperty(Handle<String> key);
   V8EXPORT bool HasRealIndexedProperty(uint32_t index);
   V8EXPORT 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.
@@ skipping 110 matching lines @@
    */
   V8EXPORT Local<Value> CallAsConstructor(int argc,
                                           Handle<Value> argv[]);
 
   V8EXPORT static Local<Object> New();
   static inline Object* Cast(Value* obj);
 
  private:
   V8EXPORT Object();
   V8EXPORT static void CheckCast(Value* obj);
-  V8EXPORT Local<Value> CheckedGetInternalField(int index);
-  V8EXPORT void* SlowGetPointerFromInternalField(int index);
-
-  /**
-   * If quick access to the internal field is possible this method
-   * returns the value.  Otherwise an empty handle is returned.
-   */
-  inline Local<Value> UncheckedGetInternalField(int index);
+  V8EXPORT Local<Value> SlowGetInternalField(int index);
+  V8EXPORT void* SlowGetAlignedPointerFromInternalField(int index);
 };
 
 
 /**
  * An instance of the built-in array constructor (ECMA-262, 15.4.2).
  */
 class Array : public Object {
  public:
   V8EXPORT uint32_t Length() const;
 
@@ skipping 190 matching lines @@
   V8EXPORT Flags GetFlags() const;
 
   static inline RegExp* Cast(v8::Value* obj);
 
  private:
   V8EXPORT static void CheckCast(v8::Value* obj);
 };
 
 
 /**
- * A JavaScript value that wraps a C++ void*.  This type of value is
- * mainly used to associate C++ data structures with JavaScript
- * objects.
- *
- * 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.
+ * A JavaScript value that wraps a C++ void*. This type of value is mainly used
+ * to associate C++ data structures with JavaScript objects.
  */
 class External : public Value {
  public:
-  V8EXPORT static Local<Value> Wrap(void* data);
-  static inline void* Unwrap(Handle<Value> obj);
+  /** Deprecated, use New instead. */
+  V8_DEPRECATED(static inline Local<Value> Wrap(void* value));
+
+  /** Deprecated, use a combination of Cast and Value instead. */
+  V8_DEPRECATED(static inline void* Unwrap(Handle<Value> obj));
 
   V8EXPORT static Local<External> New(void* value);
   static inline External* Cast(Value* obj);
   V8EXPORT void* Value() const;
  private:
-  V8EXPORT External();
   V8EXPORT static void CheckCast(v8::Value* obj);
-  static inline void* QuickUnwrap(Handle<v8::Value> obj);
-  V8EXPORT static void* FullUnwrap(Handle<v8::Value> obj);
 };
 
 
 // --- Templates ---
 
 
 /**
  * The superclass of object and function templates.
  */
 class V8EXPORT Template : public Data {
@@ skipping 1756 matching lines @@
    */
   void Exit();
 
   /** Returns true if the context has experienced an out of memory situation. */
   bool HasOutOfMemoryException();
 
   /** Returns true if V8 has a current context. */
   static bool InContext();
 
   /**
-   * 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.
+   * Gets embedder data with index 0. Deprecated, use GetEmbedderData with index
+   * 0 instead.
    */
-  void SetData(Handle<Value> data);
-  Local<Value> GetData();
+  V8_DEPRECATED(inline Local<Value> GetData());
+
+  /**
+   * Sets embedder data with index 0. Deprecated, use SetEmbedderData with index
+   * 0 instead.
+   */
+  V8_DEPRECATED(inline void SetData(Handle<Value> value));
+
+  /**
+   * Gets the embedder data with the given index, which must have been set by a
+   * previous call to SetEmbedderData with the same index. Note that index 0
+   * currently has a special meaning for Chrome's debugger.
+   */
+  inline Local<Value> GetEmbedderData(int index);
+
+  /**
+   * Sets the embedder data with the given index, growing the data as
+   * needed. Note that index 0 currently has a special meaning for Chrome's
+   * debugger.
+   */
+  void SetEmbedderData(int index, Handle<Value> value);
+
+  /**
+   * Gets a 2-byte-aligned native pointer from the embedder data with the given
+   * index, which must have bees set by a previous call to
+   * SetAlignedPointerInEmbedderData with the same index. Note that index 0
+   * currently has a special meaning for Chrome's debugger.
+   */
+  inline void* GetAlignedPointerFromEmbedderData(int index);
+
+  /**
+   * Sets a 2-byte-aligned native pointer in the embedder data with the given
+   * index, growing the data as needed. Note that index 0 currently has a
+   * special meaning for Chrome's debugger.
+   */
+  void SetAlignedPointerInEmbedderData(int index, void* value);
 
   /**
    * Control whether code generation from strings is allowed. Calling
    * this method with false will disable 'eval' and the 'Function'
    * constructor for code running in this context. If 'eval' or the
    * 'Function' constructor are used an exception will be thrown.
    *
    * If code generation from strings is not allowed the
    * V8::AllowCodeGenerationFromStrings callback will be invoked if
    * set before blocking the call to 'eval' or the 'Function'
@@ skipping 28 matching lines @@
     inline ~Scope() { context_->Exit(); }
    private:
     Handle<Context> context_;
   };
 
  private:
   friend class Value;
   friend class Script;
   friend class Object;
   friend class Function;
+
+  Local<Value> SlowGetEmbedderData(int index);
+  void* SlowGetAlignedPointerFromEmbedderData(int index);
 };
 
 
 /**
  * Multiple threads in V8 are allowed, but only one thread at a time
  * is allowed to use any given V8 isolate. See Isolate class
  * comments. The definition of 'using V8 isolate' includes
  * accessing handles or holding onto object pointers obtained
  * from V8 handles while in the particular V8 isolate.  It is up
  * to the user of V8 to ensure (perhaps with locking) that this
@@ skipping 213 matching lines @@
 
 // Smi constants for 32-bit systems.
 template <> struct SmiTagging<4> {
   static const int kSmiShiftSize = 0;
   static const int kSmiValueSize = 31;
   static inline int SmiToInt(internal::Object* value) {
     int shift_bits = kSmiTagSize + kSmiShiftSize;
     // Throw away top 32 bits and shift down (requires >> to be sign extending).
     return static_cast<int>(reinterpret_cast<intptr_t>(value)) >> shift_bits;
   }
-
-  // For 32-bit systems any 2 bytes aligned pointer can be encoded as smi
-  // with a plain reinterpret_cast.
-  static const uintptr_t kEncodablePointerMask = 0x1;
-  static const int kPointerToSmiShift = 0;
 };
 
 // Smi constants for 64-bit systems.
 template <> struct SmiTagging<8> {
   static const int kSmiShiftSize = 31;
   static const int kSmiValueSize = 32;
   static inline int SmiToInt(internal::Object* value) {
     int shift_bits = kSmiTagSize + kSmiShiftSize;
     // Shift down and throw away top 32 bits.
     return static_cast<int>(reinterpret_cast<intptr_t>(value) >> shift_bits);
   }
-
-  // To maximize the range of pointers that can be encoded
-  // in the available 32 bits, we require them to be 8 bytes aligned.
-  // This gives 2 ^ (32 + 3) = 32G address space covered.
-  // It might be not enough to cover stack allocated objects on some platforms.
-  static const int kPointerAlignment = 3;
-
-  static const uintptr_t kEncodablePointerMask =
-      ~(uintptr_t(0xffffffff) << kPointerAlignment);
-
-  static const int kPointerToSmiShift =
-      kSmiTagSize + kSmiShiftSize - kPointerAlignment;
 };
 
 typedef SmiTagging<kApiPointerSize> PlatformSmiTagging;
 const int kSmiShiftSize = PlatformSmiTagging::kSmiShiftSize;
 const int kSmiValueSize = PlatformSmiTagging::kSmiValueSize;
-const uintptr_t kEncodablePointerMask =
-    PlatformSmiTagging::kEncodablePointerMask;
-const int kPointerToSmiShift = PlatformSmiTagging::kPointerToSmiShift;
 
 /**
  * This class exports constants and functionality from within v8 that
  * is necessary to implement inline functions in the v8 api.  Don't
  * depend on functions and constants defined here.
  */
 class Internals {
  public:
   // These values match non-compiler-dependent values defined within
   // the implementation of v8.
   static const int kHeapObjectMapOffset = 0;
   static const int kMapInstanceTypeOffset = 1 * kApiPointerSize + kApiIntSize;
   static const int kStringResourceOffset = 3 * kApiPointerSize;
 
   static const int kOddballKindOffset = 3 * kApiPointerSize;
   static const int kForeignAddressOffset = kApiPointerSize;
   static const int kJSObjectHeaderSize = 3 * kApiPointerSize;
+  static const int kFixedArrayHeaderSize = 2 * kApiPointerSize;
+  static const int kContextHeaderSize = 2 * kApiPointerSize;
+  static const int kContextEmbedderDataIndex = 54;
   static const int kFullStringRepresentationMask = 0x07;
   static const int kStringEncodingMask = 0x4;
   static const int kExternalTwoByteRepresentationTag = 0x02;
   static const int kExternalAsciiRepresentationTag = 0x06;
 
   static const int kIsolateStateOffset = 0;
   static const int kIsolateEmbedderDataOffset = 1 * kApiPointerSize;
   static const int kIsolateRootsOffset = 3 * kApiPointerSize;
   static const int kUndefinedValueRootIndex = 5;
   static const int kNullValueRootIndex = 7;
   static const int kTrueValueRootIndex = 8;
   static const int kFalseValueRootIndex = 9;
-  static const int kEmptySymbolRootIndex = 117;
+  static const int kEmptySymbolRootIndex = 118;
 
   static const int kJSObjectType = 0xaa;
   static const int kFirstNonstringType = 0x80;
   static const int kOddballType = 0x82;
   static const int kForeignType = 0x85;
 
   static const int kUndefinedOddballKind = 5;
   static const int kNullOddballKind = 3;
 
   static inline bool HasHeapObjectTag(internal::Object* value) {
     return ((reinterpret_cast<intptr_t>(value) & kHeapObjectTagMask) ==
             kHeapObjectTag);
   }
 
-  static inline bool HasSmiTag(internal::Object* value) {
-    return ((reinterpret_cast<intptr_t>(value) & kSmiTagMask) == kSmiTag);
-  }
-
   static inline int SmiValue(internal::Object* value) {
     return PlatformSmiTagging::SmiToInt(value);
   }
 
   static inline int GetInstanceType(internal::Object* obj) {
     typedef internal::Object O;
     O* map = ReadField<O*>(obj, kHeapObjectMapOffset);
     return ReadField<uint8_t>(map, kMapInstanceTypeOffset);
   }
 
   static inline int GetOddballKind(internal::Object* obj) {
     typedef internal::Object O;
     return SmiValue(ReadField<O*>(obj, kOddballKindOffset));
   }
 
-  static inline void* GetExternalPointerFromSmi(internal::Object* value) {
-    const uintptr_t address = reinterpret_cast<uintptr_t>(value);
-    return reinterpret_cast<void*>(address >> kPointerToSmiShift);
-  }
-
-  static inline void* GetExternalPointer(internal::Object* obj) {
-    if (HasSmiTag(obj)) {
-      return GetExternalPointerFromSmi(obj);
-    } else if (GetInstanceType(obj) == kForeignType) {
-      return ReadField<void*>(obj, kForeignAddressOffset);
-    } else {
-      return NULL;
-    }
-  }
-
   static inline bool IsExternalTwoByteString(int instance_type) {
     int representation = (instance_type & kFullStringRepresentationMask);
     return representation == kExternalTwoByteRepresentationTag;
   }
 
   static inline bool IsInitialized(v8::Isolate* isolate) {
     uint8_t* addr = reinterpret_cast<uint8_t*>(isolate) + kIsolateStateOffset;
     return *reinterpret_cast<int*>(addr) == 1;
   }
 
@@ skipping 13 matching lines @@
     uint8_t* addr = reinterpret_cast<uint8_t*>(isolate) + kIsolateRootsOffset;
     return reinterpret_cast<internal::Object**>(addr + index * kApiPointerSize);
   }
 
   template <typename T>
   static inline T ReadField(Object* ptr, int offset) {
     uint8_t* addr = reinterpret_cast<uint8_t*>(ptr) + offset - kHeapObjectTag;
     return *reinterpret_cast<T*>(addr);
   }
 
+  template <typename T>
+  static inline T ReadEmbedderData(Context* context, int index) {
+    typedef internal::Object O;
+    typedef internal::Internals I;
+    O* ctx = *reinterpret_cast<O**>(context);
+    int embedder_data_offset = I::kContextHeaderSize +
+        (internal::kApiPointerSize * I::kContextEmbedderDataIndex);
+    O* embedder_data = I::ReadField<O*>(ctx, embedder_data_offset);
+    int value_offset =
+        I::kFixedArrayHeaderSize + (internal::kApiPointerSize * index);
+    return I::ReadField<T>(embedder_data, value_offset);
+  }
+
   static inline bool CanCastToHeapObject(void* o) { return false; }
   static inline bool CanCastToHeapObject(Context* o) { return true; }
   static inline bool CanCastToHeapObject(String* o) { return true; }
   static inline bool CanCastToHeapObject(Object* o) { return true; }
   static inline bool CanCastToHeapObject(Message* o) { return true; }
   static inline bool CanCastToHeapObject(StackTrace* o) { return true; }
   static inline bool CanCastToHeapObject(StackFrame* o) { return true; }
 };
 
 }  // namespace internal
@@ skipping 161 matching lines @@
 }
 
 
 void Template::Set(const char* name, v8::Handle<Data> value) {
   Set(v8::String::New(name), value);
 }
 
 
 Local<Value> Object::GetInternalField(int index) {
 #ifndef V8_ENABLE_CHECKS
-  Local<Value> quick_result = UncheckedGetInternalField(index);
-  if (!quick_result.IsEmpty()) return quick_result;
-#endif
-  return CheckedGetInternalField(index);
-}
-
-
-Local<Value> Object::UncheckedGetInternalField(int index) {
   typedef internal::Object O;
   typedef internal::Internals I;
   O* obj = *reinterpret_cast<O**>(this);
+  // Fast path: If the object is a plain JSObject, which is the common case, we
+  // know where to find the internal fields and can return the value directly.
   if (I::GetInstanceType(obj) == I::kJSObjectType) {
-    // If the object is a plain JSObject, which is the common case,
-    // we know where to find the internal fields and can return the
-    // value directly.
     int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index);
     O* value = I::ReadField<O*>(obj, offset);
     O** result = HandleScope::CreateHandle(value);
     return Local<Value>(reinterpret_cast<Value*>(result));
-  } else {
-    return Local<Value>();
   }
+#endif
+  return SlowGetInternalField(index);
 }
 
 
-void* External::Unwrap(Handle<v8::Value> obj) {
-#ifdef V8_ENABLE_CHECKS
-  return FullUnwrap(obj);
-#else
-  return QuickUnwrap(obj);
-#endif
+void Object::SetPointerInInternalField(int index, void* value) {
+  SetInternalField(index, External::New(value));
 }
 
 
-void* External::QuickUnwrap(Handle<v8::Value> wrapper) {
+void* Object::GetAlignedPointerFromInternalField(int index) {
+#ifndef V8_ENABLE_CHECKS
   typedef internal::Object O;
-  O* obj = *reinterpret_cast<O**>(const_cast<v8::Value*>(*wrapper));
-  return internal::Internals::GetExternalPointer(obj);
+  typedef internal::Internals I;
+  O* obj = *reinterpret_cast<O**>(this);
+  // Fast path: If the object is a plain JSObject, which is the common case, we
+  // know where to find the internal fields and can return the value directly.
+  if (I::GetInstanceType(obj) == I::kJSObjectType) {
+    int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index);
+    return I::ReadField<void*>(obj, offset);
+  }
+#endif
+  return SlowGetAlignedPointerFromInternalField(index);
 }
 
 
-void* Object::GetPointerFromInternalField(int index) {
-  typedef internal::Object O;
-  typedef internal::Internals I;
-
-  O* obj = *reinterpret_cast<O**>(this);
-
-  if (I::GetInstanceType(obj) == I::kJSObjectType) {
-    // If the object is a plain JSObject, which is the common case,
-    // we know where to find the internal fields and can return the
-    // value directly.
-    int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index);
-    O* value = I::ReadField<O*>(obj, offset);
-    return I::GetExternalPointer(value);
-  }
-
-  return SlowGetPointerFromInternalField(index);
-}
-
-
 String* String::Cast(v8::Value* value) {
 #ifdef V8_ENABLE_CHECKS
   CheckCast(value);
 #endif
   return static_cast<String*>(value);
 }
 
 
 Local<String> String::Empty(Isolate* isolate) {
   typedef internal::Object* S;
@@ skipping 168 matching lines @@
 
 
 Function* Function::Cast(v8::Value* value) {
 #ifdef V8_ENABLE_CHECKS
   CheckCast(value);
 #endif
   return static_cast<Function*>(value);
 }
 
 
+Local<Value> External::Wrap(void* value) {
+  return External::New(value);
+}
+
+
+void* External::Unwrap(Handle<v8::Value> obj) {
+  return External::Cast(*obj)->Value();
+}
+
+
 External* External::Cast(v8::Value* value) {
 #ifdef V8_ENABLE_CHECKS
   CheckCast(value);
 #endif
   return static_cast<External*>(value);
 }
 
 
 Isolate* AccessorInfo::GetIsolate() const {
   return *reinterpret_cast<Isolate**>(&args_[-3]);
@@ skipping 56 matching lines @@
   I::SetEmbedderData(this, data);
 }
 
 
 void* Isolate::GetData() {
   typedef internal::Internals I;
   return I::GetEmbedderData(this);
 }
 
 
+Local<Value> Context::GetData() {
+  return GetEmbedderData(0);
+}
+
+void Context::SetData(Handle<Value> data) {
+  SetEmbedderData(0, data);
+}
+
+
+Local<Value> Context::GetEmbedderData(int index) {
+#ifndef V8_ENABLE_CHECKS
+  typedef internal::Object O;
+  typedef internal::Internals I;
+  O** result = HandleScope::CreateHandle(I::ReadEmbedderData<O*>(this, index));
+  return Local<Value>(reinterpret_cast<Value*>(result));
+#else
+  return SlowGetEmbedderData(index);
+#endif
+}
+
+
+void* Context::GetAlignedPointerFromEmbedderData(int index) {
+#ifndef V8_ENABLE_CHECKS
+  typedef internal::Internals I;
+  return I::ReadEmbedderData<void*>(this, index);
+#else
+  return SlowGetAlignedPointerFromEmbedderData(index);
+#endif
+}
+
+
 /**
  * \example shell.cc
  * A simple shell that takes a list of expressions on the
  * command-line and executes them.
  */
 
 
 /**
  * \example process.cc
  */
 
 
 }  // namespace v8
 
 
 #undef V8EXPORT
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_