v8-array-buffer.h

Go to the documentation of this file.

// 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 <span>
 
#include "v8-local-handle.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 ArrayBuffer;
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 };
 
class V8_EXPORT BackingStore : public v8::internal::BackingStoreBase {
 public:
  ~BackingStore();
 
  void* Data() const;
 
  size_t ByteLength() const;
 
  std::span<uint8_t> ByteSpan() const;
 
  size_t MaxByteLength() const;
 
  bool IsShared() const;
 
  bool IsImmutable() const;
 
  bool IsResizableByUserJavaScript() const;
 
  void operator delete(void* ptr) { ::operator delete(ptr); }
 
  using DeleterCallback = void (*)(void* data, size_t length,
                                   void* deleter_data);
 
  static void EmptyDeleter(void* data, size_t length, void* deleter_data);
 
 private:
  BackingStore();
};
 
#if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
// Use v8::BackingStore::DeleterCallback instead.
using BackingStoreDeleterCallback = void (*)(void* data, size_t length,
                                             void* deleter_data);
 
#endif
 
class V8_EXPORT ArrayBufferBase : public Object {
 public:
  size_t ByteLength() const;
 
  size_t MaxByteLength() const;
 
  bool IsShared() const;
 
  bool IsDetachable() const;
 
  bool WasDetached() const;
 
  bool IsImmutable() const;
 
  size_t CopyArrayBufferBytes(size_t source_start, size_t bytes_to_copy,
                              Local<ArrayBufferBase> target,
                              size_t target_start) const;
 
  std::shared_ptr<BackingStore> GetBackingStore();
 
  bool IsResizableByUserJavaScript() const;
 
  void* Data() const;
 
  V8_INLINE static ArrayBufferBase* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(value);
#endif
    return static_cast<ArrayBufferBase*>(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:
  ArrayBufferBase();
  static void CheckCast(Value* obj);
  friend class ArrayBuffer;
  friend class SharedArrayBuffer;
};
 
class V8_EXPORT ArrayBuffer : public ArrayBufferBase {
 public:
  class V8_EXPORT Allocator {
   public:
    virtual ~Allocator() = default;
 
    virtual void* Allocate(size_t length) = 0;
 
    virtual void* AllocateUninitialized(size_t length) = 0;
 
    virtual void Free(void* data, size_t length) = 0;
 
    virtual size_t MaxAllocationSize() const { return kMaxByteLength; }
 
    enum class AllocationMode { kNormal, kReservation };
 
    virtual PageAllocator* GetPageAllocator() { return nullptr; }
 
#if defined(V8_COMPRESS_POINTERS) && \
    !defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
    static Allocator* NewDefaultAllocator(const IsolateGroup& group);
#endif  // defined(V8_COMPRESS_POINTERS) &&
        // !defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
 
    static Allocator* NewDefaultAllocator();
  };
 
  static MaybeLocal<ArrayBuffer> MaybeNew(
      Isolate* isolate, size_t byte_length,
      BackingStoreInitializationMode initialization_mode =
          BackingStoreInitializationMode::kZeroInitialized);
 
  static Local<ArrayBuffer> New(
      Isolate* isolate, size_t byte_length,
      BackingStoreInitializationMode initialization_mode =
          BackingStoreInitializationMode::kZeroInitialized);
 
  static Local<ArrayBuffer> New(Isolate* isolate,
                                std::shared_ptr<BackingStore> backing_store);
 
  static std::unique_ptr<BackingStore> NewBackingStore(
      Isolate* isolate, size_t byte_length,
      BackingStoreInitializationMode initialization_mode =
          BackingStoreInitializationMode::kZeroInitialized,
      BackingStoreOnFailureMode on_failure =
          BackingStoreOnFailureMode::kOutOfMemory);
 
  static std::unique_ptr<BackingStore> NewBackingStore(
      void* data, size_t byte_length, v8::BackingStore::DeleterCallback deleter,
      void* deleter_data);
 
  static std::unique_ptr<BackingStore> NewResizableBackingStore(
      size_t byte_length, size_t max_byte_length);
 
  V8_DEPRECATED(
      "Use the version which takes a key parameter (passing a null handle is "
      "ok).")
  void Detach();
 
  V8_WARN_UNUSED_RESULT Maybe<bool> Detach(v8::Local<v8::Value> key);
 
  void SetDetachKey(v8::Local<v8::Value> key);
 
  V8_INLINE static ArrayBuffer* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(value);
#endif
    return static_cast<ArrayBuffer*>(value);
  }
 
 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
 
class V8_EXPORT ArrayBufferView : public Object {
 public:
  V8_DEPRECATE_SOON("Use GetBuffer instead")
  Local<ArrayBuffer> Buffer();
  Local<ArrayBufferBase> GetBuffer();
  size_t ByteOffset();
  size_t ByteLength();
 
  size_t CopyContents(void* dest, size_t byte_length);
 
  std::span<uint8_t> GetContents(std::span<uint8_t> storage);
 
  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);
};
 
class V8_EXPORT DataView : public ArrayBufferView {
 public:
  static Local<DataView> New(Local<ArrayBufferBase> 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);
};
 
class V8_EXPORT SharedArrayBuffer : public ArrayBufferBase {
 public:
  static Local<SharedArrayBuffer> New(
      Isolate* isolate, size_t byte_length,
      BackingStoreInitializationMode initialization_mode =
          BackingStoreInitializationMode::kZeroInitialized);
 
  static MaybeLocal<SharedArrayBuffer> MaybeNew(
      Isolate* isolate, size_t byte_length,
      BackingStoreInitializationMode initialization_mode =
          BackingStoreInitializationMode::kZeroInitialized);
 
  static Local<SharedArrayBuffer> New(
      Isolate* isolate, std::shared_ptr<BackingStore> backing_store);
 
  static std::unique_ptr<BackingStore> NewBackingStore(
      Isolate* isolate, size_t byte_length,
      BackingStoreInitializationMode initialization_mode =
          BackingStoreInitializationMode::kZeroInitialized,
      BackingStoreOnFailureMode on_failure =
          BackingStoreOnFailureMode::kOutOfMemory);
 
  static std::unique_ptr<BackingStore> NewBackingStore(
      void* data, size_t byte_length, v8::BackingStore::DeleterCallback deleter,
      void* deleter_data);
 
  V8_INLINE static SharedArrayBuffer* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
    CheckCast(value);
#endif
    return static_cast<SharedArrayBuffer*>(value);
  }
 
 private:
  SharedArrayBuffer();
  static void CheckCast(Value* obj);
};
 
}  // namespace v8
 
#endif  // INCLUDE_V8_ARRAY_BUFFER_H_