[api] Clarify expectations of ArrayBuffer::Allocator in API

include/v8.h

 // Copyright 2012 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /** \mainpage V8 API Reference Guide
  *
  * V8 is Google's open source JavaScript engine.
  *
  * This set of documents provides reference material generated from the
  * V8 header file, include/v8.h.
@@ skipping 3435 matching lines @@
 enum class ArrayBufferCreationMode { kInternalized, kExternalized };
 
 
 /**
  * An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
  * This API is experimental and may change significantly.
  */
 class V8_EXPORT ArrayBuffer : public Object {
  public:
   /**
-   * Allocator that V8 uses to allocate |ArrayBuffer|'s memory.
+   * A thread-safe allocator that V8 uses to allocate |ArrayBuffer|'s memory.
    * The allocator is a global V8 setting. It has to be set via
    * Isolate::CreateParams.
    *
+   * Memory allocated through this allocator is accounted for as external

[jochen (gone - plz use gerrit), 2016/05/13 09:03:32]

But just of it's allocated by v8?

And who has to do the accounting if an array buffer is externalized?

And if the embedder allocates the backing store but then gives it as
internalized to v8?

[Michael Lippautz, 2016/05/13 09:11:22]

Yes.
Externlize unregisters it from being tracked in V8, also updating the
accounting. So the embedder needs to adjust accounting if it keeps the buffer
alive.
Other way round. The embedder should take care of first reducing the count,
because V8 will keep track of it.

That's how the implementation details currently look like -- or probably should
look like since we currently do something different (double-accounting).

[jochen (gone - plz use gerrit), 2016/05/13 09:15:03]

Can you include all that in the comment?

[Michael Lippautz, 2016/05/13 09:26:44]

Done.

+   * memory by V8.
+   *
    * This API is experimental and may change significantly.
    */
   class V8_EXPORT Allocator { // NOLINT
    public:
     virtual ~Allocator() {}
 
     /**
      * Allocate |length| bytes. Return NULL if allocation is not successful.
      * Memory should be initialized to zeroes.
      */
@@ skipping 5262 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // INCLUDE_V8_H_