@downdraft/native-mobile-android-arm64 0.0.0 → 0.1.1

package/include/node/v8-array-buffer.h

@@ -0,0 +1,646 @@
+// Copyright 2021 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.
+
+#ifndef INCLUDE_V8_ARRAY_BUFFER_H_
+#define INCLUDE_V8_ARRAY_BUFFER_H_
+
+#include <stddef.h>
+
+#include <memory>
+
+#include "v8-local-handle.h"  // NOLINT(build/include_directory)
+#include "v8-memory-span.h"   // NOLINT(build/include_directory)
+#include "v8-object.h"        // NOLINT(build/include_directory)
+#include "v8-platform.h"      // NOLINT(build/include_directory)
+#include "v8config.h"         // NOLINT(build/include_directory)
+
+namespace v8 {
+
+class SharedArrayBuffer;
+
+#if defined(V8_COMPRESS_POINTERS) && \
+    !defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
+class IsolateGroup;
+#endif
+
+#ifndef V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT
+// Defined using gn arg `v8_array_buffer_internal_field_count`.
+#define V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT 2
+#endif
+
+enum class ArrayBufferCreationMode { kInternalized, kExternalized };
+enum class BackingStoreInitializationMode { kZeroInitialized, kUninitialized };
+enum class BackingStoreOnFailureMode { kReturnNull, kOutOfMemory };
+
+/**
+ * A wrapper around the backing store (i.e. the raw memory) of an array buffer.
+ * See a document linked in http://crbug.com/v8/9908 for more information.
+ *
+ * The allocation and destruction of backing stores is generally managed by
+ * V8. Clients should always use standard C++ memory ownership types (i.e.
+ * std::unique_ptr and std::shared_ptr) to manage lifetimes of backing stores
+ * properly, since V8 internal objects may alias backing stores.
+ *
+ * This object does not keep the underlying |ArrayBuffer::Allocator| alive by
+ * default. Use Isolate::CreateParams::array_buffer_allocator_shared when
+ * creating the Isolate to make it hold a reference to the allocator itself.
+ */
+class V8_EXPORT BackingStore : public v8::internal::BackingStoreBase {
+ public:
+  ~BackingStore();
+
+  /**
+   * Return a pointer to the beginning of the memory block for this backing
+   * store. The pointer is only valid as long as this backing store object
+   * lives.
+   */
+  void* Data() const;
+
+  /**
+   * The length (in bytes) of this backing store.
+   */
+  size_t ByteLength() const;
+
+  /**
+   * The maximum length (in bytes) that this backing store may grow to.
+   *
+   * If this backing store was created for a resizable ArrayBuffer or a growable
+   * SharedArrayBuffer, it is >= ByteLength(). Otherwise it is ==
+   * ByteLength().
+   */
+  size_t MaxByteLength() const;
+
+  /**
+   * Indicates whether the backing store was created for an ArrayBuffer or
+   * a SharedArrayBuffer.
+   */
+  bool IsShared() const;
+
+  /**
+   * Indicates whether the backing store is immutable.
+   */
+  bool IsImmutable() const;
+
+  /**
+   * Indicates whether the backing store was created for a resizable ArrayBuffer
+   * or a growable SharedArrayBuffer, and thus may be resized by user JavaScript
+   * code.
+   */
+  bool IsResizableByUserJavaScript() const;
+
+  /**
+   * Prevent implicit instantiation of operator delete with size_t argument.
+   * The size_t argument would be incorrect because ptr points to the
+   * internal BackingStore object.
+   */
+  void operator delete(void* ptr) { ::operator delete(ptr); }
+
+  /**
+   * This callback is used only if the memory block for a BackingStore cannot be
+   * allocated with an ArrayBuffer::Allocator. In such cases the destructor of
+   * the BackingStore invokes the callback to free the memory block.
+   */
+  using DeleterCallback = void (*)(void* data, size_t length,
+                                   void* deleter_data);
+
+  /**
+   * If the memory block of a BackingStore is static or is managed manually,
+   * then this empty deleter along with nullptr deleter_data can be passed to
+   * ArrayBuffer::NewBackingStore to indicate that.
+   *
+   * The manually managed case should be used with caution and only when it
+   * is guaranteed that the memory block freeing happens after detaching its
+   * ArrayBuffer.
+   */
+  static void EmptyDeleter(void* data, size_t length, void* deleter_data);
+
+ private:
+  /**
+   * See [Shared]ArrayBuffer::GetBackingStore and
+   * [Shared]ArrayBuffer::NewBackingStore.
+   */
+  BackingStore();
+};
+
+#if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
+// Use v8::BackingStore::DeleterCallback instead.
+using BackingStoreDeleterCallback = void (*)(void* data, size_t length,
+                                             void* deleter_data);
+
+#endif
+
+/**
+ * An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
+ */
+class V8_EXPORT ArrayBuffer : public Object {
+ public:
+  /**
+   * 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 by V8 is accounted for as external
+   * memory by V8. Note that V8 keeps track of the memory for all internalized
+   * |ArrayBuffer|s. Responsibility for tracking external memory (using
+   * Isolate::AdjustAmountOfExternalAllocatedMemory) is handed over to the
+   * embedder upon externalization and taken over upon internalization (creating
+   * an internalized buffer from an existing buffer).
+   *
+   * Note that it is unsafe to call back into V8 from any of the allocator
+   * functions.
+   */
+  class V8_EXPORT Allocator {
+   public:
+    virtual ~Allocator() = default;
+
+    /**
+     * Allocate |length| bytes. Return nullptr if allocation is not successful.
+     * Memory should be initialized to zeroes.
+     */
+    virtual void* Allocate(size_t length) = 0;
+
+    /**
+     * Allocate |length| bytes. Return nullptr if allocation is not successful.
+     * Memory does not have to be initialized.
+     */
+    virtual void* AllocateUninitialized(size_t length) = 0;
+
+    /**
+     * Free the memory block of size |length|, pointed to by |data|.
+     * That memory is guaranteed to be previously allocated by |Allocate|.
+     */
+    virtual void Free(void* data, size_t length) = 0;
+
+    /**
+     * Returns a size_t that determines the largest ArrayBuffer that can be
+     * allocated.  Override if your Allocator is more restrictive than the
+     * default.  Will only be called once, and the value returned will be
+     * cached.
+     * Should not return a value that is larger than kMaxByteLength.
+     */
+    virtual size_t MaxAllocationSize() const { return kMaxByteLength; }
+
+    /**
+     * ArrayBuffer allocation mode. kNormal is a malloc/free style allocation,
+     * while kReservation is for larger allocations with the ability to set
+     * access permissions.
+     */
+    enum class AllocationMode { kNormal, kReservation };
+
+    /**
+     * Returns page allocator used by this Allocator instance.
+     *
+     * When the sandbox used by Allocator it is expected that this returns
+     * sandbox's page allocator.
+     * Otherwise, it should return system page allocator.
+     */
+    virtual PageAllocator* GetPageAllocator() { return nullptr; }
+
+#if defined(V8_COMPRESS_POINTERS) && \
+    !defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
+    /**
+     * Convenience allocator.
+     *
+     * When the sandbox is enabled, this allocator will allocate its backing
+     * memory inside the sandbox that belongs to the passed isolate group.
+     * Otherwise, it will rely on malloc/free.
+     *
+     * Caller takes ownership, i.e. the returned object needs to be freed using
+     * |delete allocator| once it is no longer in use.
+     */
+    static Allocator* NewDefaultAllocator(const IsolateGroup& group);
+#endif  // defined(V8_COMPRESS_POINTERS) &&
+        // !defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
+
+    /**
+     * Convenience allocator.
+     *
+     * When the sandbox is enabled, this allocator will allocate its backing
+     * memory inside the default global sandbox. Otherwise, it will rely on
+     * malloc/free.
+     *
+     * Caller takes ownership, i.e. the returned object needs to be freed using
+     * |delete allocator| once it is no longer in use.
+     */
+    static Allocator* NewDefaultAllocator();
+  };
+
+  /**
+   * Data length in bytes.
+   */
+  size_t ByteLength() const;
+
+  /**
+   * Maximum length in bytes.
+   */
+  size_t MaxByteLength() const;
+
+  /**
+   * Attempt to create a new ArrayBuffer. Allocate |byte_length| bytes.
+   * Allocated memory will be owned by a created ArrayBuffer and
+   * will be deallocated when it is garbage-collected,
+   * unless the object is externalized. If allocation fails, the Maybe
+   * returned will be empty.
+   */
+  static MaybeLocal<ArrayBuffer> MaybeNew(
+      Isolate* isolate, size_t byte_length,
+      BackingStoreInitializationMode initialization_mode =
+          BackingStoreInitializationMode::kZeroInitialized);
+
+  /**
+   * Create a new ArrayBuffer. Allocate |byte_length| bytes, which are either
+   * zero-initialized or uninitialized. Allocated memory will be owned by a
+   * created ArrayBuffer and will be deallocated when it is garbage-collected,
+   * unless the object is externalized.
+   */
+  static Local<ArrayBuffer> New(
+      Isolate* isolate, size_t byte_length,
+      BackingStoreInitializationMode initialization_mode =
+          BackingStoreInitializationMode::kZeroInitialized);
+
+  /**
+   * Create a new ArrayBuffer with an existing backing store.
+   * The created array keeps a reference to the backing store until the array
+   * is garbage collected. Note that the IsExternal bit does not affect this
+   * reference from the array to the backing store.
+   *
+   * In future IsExternal bit will be removed. Until then the bit is set as
+   * follows. If the backing store does not own the underlying buffer, then
+   * the array is created in externalized state. Otherwise, the array is created
+   * in internalized state. In the latter case the array can be transitioned
+   * to the externalized state using Externalize(backing_store).
+   */
+  static Local<ArrayBuffer> New(Isolate* isolate,
+                                std::shared_ptr<BackingStore> backing_store);
+
+  /**
+   * Returns a new standalone BackingStore that is allocated using the array
+   * buffer allocator of the isolate. The allocation can either be zero
+   * initialized, or uninitialized. The result can be later passed to
+   * ArrayBuffer::New.
+   *
+   * If the allocator returns nullptr, then the function may cause GCs in the
+   * given isolate and re-try the allocation.
+   *
+   * If GCs do not help and on_failure is kOutOfMemory, then the
+   * function will crash with an out-of-memory error.
+   *
+   * Otherwise if GCs do not help (or the allocation is too large for GCs to
+   * help) and on_failure is kReturnNull, then a null result is returned.
+   */
+  static std::unique_ptr<BackingStore> NewBackingStore(
+      Isolate* isolate, size_t byte_length,
+      BackingStoreInitializationMode initialization_mode =
+          BackingStoreInitializationMode::kZeroInitialized,
+      BackingStoreOnFailureMode on_failure =
+          BackingStoreOnFailureMode::kOutOfMemory);
+
+  /**
+   * Returns a new standalone BackingStore that takes over the ownership of
+   * the given buffer. The destructor of the BackingStore invokes the given
+   * deleter callback.
+   *
+   * The result can be later passed to ArrayBuffer::New. The raw pointer
+   * to the buffer must not be passed again to any V8 API function.
+   */
+  static std::unique_ptr<BackingStore> NewBackingStore(
+      void* data, size_t byte_length, v8::BackingStore::DeleterCallback deleter,
+      void* deleter_data);
+
+  /**
+   * Returns a new resizable standalone BackingStore that is allocated using the
+   * array buffer allocator of the isolate. The result can be later passed to
+   * ArrayBuffer::New.
+   *
+   * |byte_length| must be <= |max_byte_length|.
+   *
+   * This function is usable without an isolate. Unlike |NewBackingStore| calls
+   * with an isolate, GCs cannot be triggered, and there are no
+   * retries. Allocation failure will cause the function to crash with an
+   * out-of-memory error.
+   */
+  static std::unique_ptr<BackingStore> NewResizableBackingStore(
+      size_t byte_length, size_t max_byte_length);
+
+  /**
+   * Returns true if this ArrayBuffer may be detached.
+   */
+  bool IsDetachable() const;
+
+  /**
+   * Returns true if this ArrayBuffer has been detached.
+   */
+  bool WasDetached() const;
+
+  /**
+   * Returns true if this ArrayBuffer is immutable.
+   */
+  bool IsImmutable() const;
+
+  /**
+   * Copy up to |bytes_to_copy| bytes from this ArrayBuffer starting at
+   * position |source_start| to the target ArrayBuffer starting at position
+   * |target_start|. Nothing is copied if the source ArrayBuffer is detached,
+   * or if the target ArrayBuffer is detached or immutable.
+   * Returns the number of bytes actually copied.
+   */
+  size_t CopyArrayBufferBytes(size_t source_start, size_t bytes_to_copy,
+                              Local<ArrayBuffer> target,
+                              size_t target_start) const;
+
+  /**
+   * Detaches this ArrayBuffer and all its views (typed arrays).
+   * Detaching sets the byte length of the buffer and all typed arrays to zero,
+   * preventing JavaScript from ever accessing underlying backing store.
+   * ArrayBuffer should have been externalized and must be detachable.
+   */
+  V8_DEPRECATED(
+      "Use the version which takes a key parameter (passing a null handle is "
+      "ok).")
+  void Detach();
+
+  /**
+   * Detaches this ArrayBuffer and all its views (typed arrays).
+   * Detaching sets the byte length of the buffer and all typed arrays to zero,
+   * preventing JavaScript from ever accessing underlying backing store.
+   * ArrayBuffer should have been externalized and must be detachable. Returns
+   * Nothing if the key didn't pass the [[ArrayBufferDetachKey]] check,
+   * Just(true) otherwise.
+   */
+  V8_WARN_UNUSED_RESULT Maybe<bool> Detach(v8::Local<v8::Value> key);
+
+  /**
+   * Sets the ArrayBufferDetachKey.
+   */
+  void SetDetachKey(v8::Local<v8::Value> key);
+
+  /**
+   * Get a shared pointer to the backing store of this array buffer. This
+   * pointer coordinates the lifetime management of the internal storage
+   * with any live ArrayBuffers on the heap, even across isolates. The embedder
+   * should not attempt to manage lifetime of the storage through other means.
+   *
+   * The returned shared pointer will not be empty, even if the ArrayBuffer has
+   * been detached. Use |WasDetached| to tell if it has been detached instead.
+   */
+  std::shared_ptr<BackingStore> GetBackingStore();
+
+  /**
+   * More efficient shortcut for
+   * GetBackingStore()->IsResizableByUserJavaScript().
+   */
+  bool IsResizableByUserJavaScript() const;
+
+  /**
+   * More efficient shortcut for GetBackingStore()->Data(). The returned pointer
+   * is valid as long as the ArrayBuffer is alive.
+   */
+  void* Data() const;
+
+  V8_INLINE static ArrayBuffer* Cast(Value* value) {
+#ifdef V8_ENABLE_CHECKS
+    CheckCast(value);
+#endif
+    return static_cast<ArrayBuffer*>(value);
+  }
+
+  static constexpr int kInternalFieldCount =
+      V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
+  static constexpr int kEmbedderFieldCount = kInternalFieldCount;
+
+#if V8_ENABLE_SANDBOX
+  static constexpr size_t kMaxByteLength =
+      internal::kMaxSafeBufferSizeForSandbox;
+#elif V8_HOST_ARCH_32_BIT
+  static constexpr size_t kMaxByteLength = std::numeric_limits<int>::max();
+#else
+  // The maximum safe integer (2^53 - 1).
+  static constexpr size_t kMaxByteLength =
+      static_cast<size_t>((uint64_t{1} << 53) - 1);
+#endif
+
+ private:
+  ArrayBuffer();
+  static void CheckCast(Value* obj);
+  friend class TypedArray;
+};
+
+#ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT
+// Defined using gn arg `v8_array_buffer_view_internal_field_count`.
+#define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2
+#endif
+
+/**
+ * A base class for an instance of one of "views" over ArrayBuffer,
+ * including TypedArrays and DataView (ES6 draft 15.13).
+ */
+class V8_EXPORT ArrayBufferView : public Object {
+ public:
+  /**
+   * Returns underlying ArrayBuffer.
+   */
+  Local<ArrayBuffer> Buffer();
+  /**
+   * Byte offset in |Buffer|.
+   */
+  size_t ByteOffset();
+  /**
+   * Size of a view in bytes.
+   */
+  size_t ByteLength();
+
+  /**
+   * Copy the contents of the ArrayBufferView's buffer to an embedder defined
+   * memory without additional overhead that calling ArrayBufferView::Buffer
+   * might incur.
+   *
+   * Will write at most min(|byte_length|, ByteLength) bytes starting at
+   * ByteOffset of the underlying buffer to the memory starting at |dest|.
+   * Returns the number of bytes actually written.
+   */
+  size_t CopyContents(void* dest, size_t byte_length);
+
+  /**
+   * Returns the contents of the ArrayBufferView's buffer as a MemorySpan. If
+   * the contents are on the V8 heap, they get copied into `storage`. Otherwise
+   * a view into the off-heap backing store is returned. The provided storage
+   * should be at least as large as the maximum on-heap size of a TypedArray,
+   * was defined in gn with `typed_array_max_size_in_heap`. The default value is
+   * 64 bytes.
+   */
+  v8::MemorySpan<uint8_t> GetContents(v8::MemorySpan<uint8_t> storage);
+
+  /**
+   * Returns true if ArrayBufferView's backing ArrayBuffer has already been
+   * allocated.
+   */
+  bool HasBuffer() const;
+
+  V8_INLINE static ArrayBufferView* Cast(Value* value) {
+#ifdef V8_ENABLE_CHECKS
+    CheckCast(value);
+#endif
+    return static_cast<ArrayBufferView*>(value);
+  }
+
+  static constexpr int kInternalFieldCount =
+      V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT;
+  static const int kEmbedderFieldCount = kInternalFieldCount;
+
+ private:
+  ArrayBufferView();
+  static void CheckCast(Value* obj);
+};
+
+/**
+ * An instance of DataView constructor (ES6 draft 15.13.7).
+ */
+class V8_EXPORT DataView : public ArrayBufferView {
+ public:
+  static Local<DataView> New(Local<ArrayBuffer> array_buffer,
+                             size_t byte_offset, size_t length);
+  static Local<DataView> New(Local<SharedArrayBuffer> shared_array_buffer,
+                             size_t byte_offset, size_t length);
+  V8_INLINE static DataView* Cast(Value* value) {
+#ifdef V8_ENABLE_CHECKS
+    CheckCast(value);
+#endif
+    return static_cast<DataView*>(value);
+  }
+
+ private:
+  DataView();
+  static void CheckCast(Value* obj);
+};
+
+/**
+ * An instance of the built-in SharedArrayBuffer constructor.
+ */
+class V8_EXPORT SharedArrayBuffer : public Object {
+ public:
+  /**
+   * Data length in bytes.
+   */
+  size_t ByteLength() const;
+
+  /**
+   * Maximum length in bytes.
+   */
+  size_t MaxByteLength() const;
+
+  /**
+   * Create a new SharedArrayBuffer. Allocate |byte_length| bytes, which are
+   * either zero-initialized or uninitialized. Allocated memory will be owned by
+   * a created SharedArrayBuffer and will be deallocated when it is
+   * garbage-collected, unless the object is externalized.
+   */
+  static Local<SharedArrayBuffer> New(
+      Isolate* isolate, size_t byte_length,
+      BackingStoreInitializationMode initialization_mode =
+          BackingStoreInitializationMode::kZeroInitialized);
+
+  /**
+   * Create a new SharedArrayBuffer. Allocate |byte_length| bytes, which are
+   * either zero-initialized or uninitialized. Allocated memory will be owned by
+   * a created SharedArrayBuffer and will be deallocated when it is
+   * garbage-collected, unless the object is externalized.  If allocation
+   * fails, the Maybe returned will be empty.
+   */
+  static MaybeLocal<SharedArrayBuffer> MaybeNew(
+      Isolate* isolate, size_t byte_length,
+      BackingStoreInitializationMode initialization_mode =
+          BackingStoreInitializationMode::kZeroInitialized);
+
+  /**
+   * Create a new SharedArrayBuffer with an existing backing store.
+   * The created array keeps a reference to the backing store until the array
+   * is garbage collected. Note that the IsExternal bit does not affect this
+   * reference from the array to the backing store.
+   *
+   * In future IsExternal bit will be removed. Until then the bit is set as
+   * follows. If the backing store does not own the underlying buffer, then
+   * the array is created in externalized state. Otherwise, the array is created
+   * in internalized state. In the latter case the array can be transitioned
+   * to the externalized state using Externalize(backing_store).
+   */
+  static Local<SharedArrayBuffer> New(
+      Isolate* isolate, std::shared_ptr<BackingStore> backing_store);
+
+  /**
+   * Returns a new standalone BackingStore that is allocated using the array
+   * buffer allocator of the isolate. The allocation can either be zero
+   * initialized, or uninitialized. The result can be later passed to
+   * SharedArrayBuffer::New.
+   *
+   * If the allocator returns nullptr, then the function may cause GCs in the
+   * given isolate and re-try the allocation.
+   *
+   * If on_failure is kOutOfMemory and GCs do not help, then the function will
+   * crash with an out-of-memory error.
+   *
+   * Otherwise, if on_failure is kReturnNull and GCs do not help (or the
+   * byte_length is so large that the allocation cannot succeed), then a null
+   * result is returned.
+   */
+  static std::unique_ptr<BackingStore> NewBackingStore(
+      Isolate* isolate, size_t byte_length,
+      BackingStoreInitializationMode initialization_mode =
+          BackingStoreInitializationMode::kZeroInitialized,
+      BackingStoreOnFailureMode on_failure =
+          BackingStoreOnFailureMode::kOutOfMemory);
+
+  /**
+   * Returns a new standalone BackingStore that takes over the ownership of
+   * the given buffer. The destructor of the BackingStore invokes the given
+   * deleter callback.
+   *
+   * The result can be later passed to SharedArrayBuffer::New. The raw pointer
+   * to the buffer must not be passed again to any V8 functions.
+   */
+  static std::unique_ptr<BackingStore> NewBackingStore(
+      void* data, size_t byte_length, v8::BackingStore::DeleterCallback deleter,
+      void* deleter_data);
+
+  /**
+   * Get a shared pointer to the backing store of this array buffer. This
+   * pointer coordinates the lifetime management of the internal storage
+   * with any live ArrayBuffers on the heap, even across isolates. The embedder
+   * should not attempt to manage lifetime of the storage through other means.
+   */
+  std::shared_ptr<BackingStore> GetBackingStore();
+
+  /**
+   * More efficient shortcut for GetBackingStore()->Data(). The returned pointer
+   * is valid as long as the ArrayBuffer is alive.
+   */
+  void* Data() const;
+
+  /**
+   * Copy up to |bytes_to_copy| bytes from this SharedArrayBuffer starting at
+   * position |source_start| to the target SharedArrayBuffer starting at
+   * position |target_start|.
+   * Returns the number of bytes actually copied.
+   */
+  size_t CopyArrayBufferBytes(size_t source_start, size_t bytes_to_copy,
+                              Local<SharedArrayBuffer> target,
+                              size_t target_start) const;
+
+  V8_INLINE static SharedArrayBuffer* Cast(Value* value) {
+#ifdef V8_ENABLE_CHECKS
+    CheckCast(value);
+#endif
+    return static_cast<SharedArrayBuffer*>(value);
+  }
+
+  static constexpr int kInternalFieldCount =
+      V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
+
+ private:
+  SharedArrayBuffer();
+  static void CheckCast(Value* obj);
+};
+
+}  // namespace v8
+
+#endif  // INCLUDE_V8_ARRAY_BUFFER_H_