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

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index 52b6192b87643bec0a0abff62dac9864da01baf7..7aba9117b9a136afb181efe51f1fb4532cf14e55 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -3453,10 +3453,13 @@ enum class ArrayBufferCreationMode { kInternalized, kExternalized };
 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