Change ArrayBuffer API and implementation to use embedder-provided allocator.

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index e99c6d9a98035d9b6abe7d26705c7ae1b02a280e..f3e753e690dd8457b9919e933d38c2e7afd8be8c 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -2370,30 +2370,6 @@ class V8EXPORT Function : public Object {
   static void CheckCast(Value* obj);
 };
 
-/**
- * The contents of an |ArrayBuffer|. Externalization of |ArrayBuffer|
- * populates an instance of this class with a pointer to data and byte length.
- *
- * |ArrayBufferContents| is the owner of its data. When an instance of
- * this class is destructed, the |Data| is freed.
- *
- * This API is experimental and may change significantly.
- */
-class V8EXPORT ArrayBufferContents {
- public:
-  ArrayBufferContents() : data_(NULL), byte_length_(0) {}
-  ~ArrayBufferContents();
-
-  void* Data() const { return data_; }
-  size_t ByteLength() const { return byte_length_; }
-
- private:
-  void* data_;
-  size_t byte_length_;
-
-  friend class ArrayBuffer;
-};
-
 #ifndef V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT
 #define V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT 2
 #endif
@@ -2405,6 +2381,53 @@ class V8EXPORT ArrayBufferContents {
 class V8EXPORT ArrayBuffer : public Object {
  public:
   /**
+   * Allocator that V8 uses to allocate |ArrayBuffer|'s memory.
+   * The allocator is a global V8 setting. It should be set with
+   * V8::SetArrayBufferAllocator prior to creation of a first ArrayBuffer.
+   *
+   * This API is experimental and may change significantly.
+   */
+  class V8EXPORT Allocator { // NOLINT
+   public:
+    virtual ~Allocator() {}
+
+    /**
+     * Allocate |length| bytes. Return NULL if allocation is not successful.
+     */
+    virtual void* Allocate(size_t length) = 0;

[Sven Panne, 2013/06/11 09:54:37]

I think it might make sense to include the current Isolate in the arguments of
Allocate/Free, even if we don't need it right now. In other places we have
always regretted our decision to leave it out so far, and we have it at the call
sites, anyway. Just to be future-proof...

[Dmitry Lomov (no reviews), 2013/06/11 10:40:09]

ArrayBuffer allocator very specifically does not depend on current isolate. One
of our primary use cases is WebKit where ArrayBuffers backing store can move
between isolates, so if it is allocated in the context of one isolate, it might
be freed in the context of another. 
On 2013/06/11 09:54:37, Sven Panne wrote:

+    /**
+     * Free the memory pointed to |data|. That memory is guaranteed to be
+     * previously allocated by |Allocate|.
+     */
+    virtual void Free(void* data) = 0;
+  };
+
+  /**
+   * The contents of an |ArrayBuffer|. Externalization of |ArrayBuffer|
+   * returns an instance of this class, populated, with a pointer to data
+   * and byte length.
+   *
+   * The Data pointer of ArrayBuffer::Contents is always allocated with
+   * Allocator::Allocate that is set with V8::SetArrayBufferAllocator.
+   *
+   * This API is experimental and may change significantly.
+   */
+  class V8EXPORT Contents { // NOLINT
+   public:
+    Contents() : data_(NULL), byte_length_(0) {}
+
+    void* Data() const { return data_; }
+    size_t ByteLength() const { return byte_length_; }
+
+   private:
+    void* data_;
+    size_t byte_length_;
+
+    friend class ArrayBuffer;
+  };
+
+
+  /**
    * Data length in bytes.
    */
   size_t ByteLength() const;
@@ -2440,14 +2463,18 @@ class V8EXPORT ArrayBuffer : public Object {
   void Neuter();
 
   /**
-   * Pass the ownership of this ArrayBuffer's backing store to
-   * a given ArrayBufferContents.
+   * Make this ArrayBuffer external. The pointer to underlying memory block
+   * and byte length are returned as |Contents| structure. After ArrayBuffer
+   * had been etxrenalized, it does no longer owns the memory block. The caller
+   * should take steps to free memory when it is no longer needed.
+   *
+   * The memory block is guaranteed to be allocated with |Allocator::Allocate|
+   * that has been set with V8::SetArrayBufferAllocator.
    */
-  void Externalize(ArrayBufferContents* contents);
+  Contents Externalize();
 
   V8_INLINE(static ArrayBuffer* Cast(Value* obj));
 
-
   static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
 
  private:
@@ -4193,6 +4220,14 @@ class V8EXPORT V8 {
       AllowCodeGenerationFromStringsCallback that);
 
   /**
+   * Set allocator to use for ArrayBuffer memory.
+   * The allocator should be set only once. The allocator should be set
+   * before any code tha uses ArrayBuffers is executed.
+   * This allocator is used in all isolates.
+   */
+  static void SetArrayBufferAllocator(ArrayBuffer::Allocator* allocator);
+
+  /**
    * Ignore out-of-memory exceptions.
    *
    * V8 running out of memory is treated as a fatal error by default.