src/aliased_struct.h

#ifndef SRC_ALIASED_STRUCT_H_
#define SRC_ALIASED_STRUCT_H_

#if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

#include <memory>
#include <vector>
#include "node_internals.h"
#include "v8.h"

namespace node {

// AliasedStruct is a utility that allows uses a V8 Backing Store
// to be exposed to the C++/C side as a struct and to the
// JavaScript side as an ArrayBuffer to efficiently share
// data without marshalling. It is similar in nature to
// AliasedBuffer.
//
//   struct Foo { int x; }
//
//   AliasedStruct<Foo> foo;
//   foo->x = 1;
//
//   Local<ArrayBuffer> ab = foo.GetArrayBuffer();
template <typename T>
class AliasedStruct final {
 public:
  template <typename... Args>
  explicit AliasedStruct(v8::Isolate* isolate, Args&&... args);

  inline AliasedStruct(const AliasedStruct& that);

  inline ~AliasedStruct();

  inline AliasedStruct& operator=(AliasedStruct&& that) noexcept;

  v8::Local<v8::ArrayBuffer> GetArrayBuffer() const {
    return buffer_.Get(isolate_);
  }

  const T* Data() const { return ptr_; }

  T* Data() { return ptr_; }

  const T& operator*() const { return *ptr_; }

  T& operator*()  { return *ptr_; }

  const T* operator->() const { return ptr_; }

  T* operator->() { return ptr_; }

 private:
  v8::Isolate* isolate_;
  std::shared_ptr<v8::BackingStore> store_;
  T* ptr_;
  v8::Global<v8::ArrayBuffer> buffer_;
};

// ---------------------------------------------------------------------------
// ArenaSlot — type-erased handle to a slot in an AliasedStructArena page.
// This can be stored in headers where T is incomplete. The typed accessors
// are provided via a thin typed wrapper (AliasedStructArena<T>::Slot).
struct ArenaSlotBase {
  // Opaque page pointer — only the arena knows the concrete type.
  void* page = nullptr;
  void* ptr = nullptr;
  uint32_t index = 0;
  size_t byte_offset = 0;

  explicit operator bool() const { return ptr != nullptr; }

  // Returns the page's ArrayBuffer. Implemented below after ArenaPageHeader.
  v8::Local<v8::ArrayBuffer> GetArrayBuffer(v8::Isolate* isolate) const;

  size_t GetByteOffset() const { return byte_offset; }

  // Returns the page's cached DataView over the full page.
  // Callers use byte_offset to index into the correct slot region.
  v8::Local<v8::DataView> GetPageDataView(v8::Isolate* isolate) const;

  // Returns the page's cached BigUint64Array over the full page.
  // Callers use byte_offset / sizeof(uint64_t) to index into the
  // correct slot region.
  v8::Local<v8::BigUint64Array> GetPageBigUint64Array(
      v8::Isolate* isolate) const;
};

// ---------------------------------------------------------------------------
// AliasedStructArena<T> — pool allocator for AliasedStruct-style shared
// memory.  Instead of creating a separate ArrayBuffer + BackingStore per
// instance, the arena pre-allocates pages of N slots backed by a single
// ArrayBuffer each.  Callers receive a Slot handle that provides the same
// T*/operator-> interface as AliasedStruct, plus the ability to create a
// JS typed-array view over just that slot's region of the page buffer.
//
// Pages target kPageBytes (default 16 KB) for L1 cache residency during
// sequential access patterns.  Slots are recycled via an intrusive
// freelist, and empty pages are dropped when their last slot is released.
//
// Usage:
//   AliasedStructArena<MyState> arena;
//   auto slot = arena.Allocate(isolate);
//   slot->some_field = 42;
//   auto view = slot.GetArrayBuffer(isolate);  // JS-visible view
//   ...
//   arena.Release(std::move(slot));             // return to freelist
//
template <typename T, size_t kPageBytes = 16384>
class AliasedStructArena final {
 public:
  static constexpr size_t kSlotsPerPage = kPageBytes / sizeof(T);
  static_assert(kSlotsPerPage >= 4, "Page too small for type T");
  static_assert(sizeof(T) >= sizeof(uint32_t),
                "T must be at least 4 bytes for freelist linkage");

  AliasedStructArena() = default;
  ~AliasedStructArena() = default;

  AliasedStructArena(const AliasedStructArena&) = delete;
  AliasedStructArena& operator=(const AliasedStructArena&) = delete;

  struct Page {
    std::shared_ptr<v8::BackingStore> store;
    v8::Global<v8::ArrayBuffer> buffer;
    // Lazily created full-page views shared by all slots in
    // this page. Typically only one is used per arena.
    v8::Global<v8::DataView> data_view;
    v8::Global<v8::BigUint64Array> big_uint64_array;
    size_t page_byte_length = 0;
    T* base = nullptr;
    uint32_t free_head = 0;
    uint32_t used_count = 0;
    static constexpr uint32_t kNoFreeSlot = UINT32_MAX;

    void Init(v8::Isolate* isolate) {
      const v8::HandleScope handle_scope(isolate);
      const size_t total_bytes = kSlotsPerPage * sizeof(T);
      store = v8::ArrayBuffer::NewBackingStore(isolate, total_bytes);
      memset(store->Data(), 0, total_bytes);
      base = static_cast<T*>(store->Data());
      page_byte_length = total_bytes;
      v8::Local<v8::ArrayBuffer> ab = v8::ArrayBuffer::New(isolate, store);
      buffer = v8::Global<v8::ArrayBuffer>(isolate, ab);

      // Build freelist: each slot points to the next.
      for (uint32_t i = 0; i < kSlotsPerPage - 1; i++) {
        *reinterpret_cast<uint32_t*>(&base[i]) = i + 1;
      }
      *reinterpret_cast<uint32_t*>(&base[kSlotsPerPage - 1]) = kNoFreeSlot;
      free_head = 0;
      used_count = 0;
    }

    bool HasFreeSlots() const { return free_head != kNoFreeSlot; }
  };

  // Typed slot handle — wraps ArenaSlotBase with T* accessors.
  class Slot : public ArenaSlotBase {
   public:
    Slot() = default;

    const T& operator*() const { return *static_cast<T*>(ptr); }
    T& operator*() { return *static_cast<T*>(ptr); }
    const T* operator->() const { return static_cast<T*>(ptr); }
    T* operator->() { return static_cast<T*>(ptr); }
    T* Data() { return static_cast<T*>(ptr); }
    const T* Data() const { return static_cast<T*>(ptr); }
  };

  // Allocate a slot, placement-constructing T with the given args.
  // Creates a new page if all existing pages are full.
  template <typename... Args>
  Slot Allocate(v8::Isolate* isolate, Args&&... args);

  // Release a slot back to the arena freelist.  Calls ~T() and zeros
  // the memory so that any JS views see clean data.
  void Release(Slot&& slot);

  // Release a slot given a type-erased ArenaSlotBase reference.
  // Convenience for callers that store ArenaSlotBase in headers where
  // T is incomplete.
  void ReleaseSlot(ArenaSlotBase& base);

 private:
  Page* FindOrCreatePage(v8::Isolate* isolate);

  std::vector<std::unique_ptr<Page>> pages_;
};

// ArenaSlotBase accessors need to reach the v8::Globals inside a Page.
// All AliasedStructArena<T>::Page types share the same leading layout.
// The page_byte_length field allows lazy view creation without knowing T.
namespace detail {
struct ArenaPageHeader {
  std::shared_ptr<v8::BackingStore> store;
  v8::Global<v8::ArrayBuffer> buffer;
  v8::Global<v8::DataView> data_view;
  v8::Global<v8::BigUint64Array> big_uint64_array;
  size_t page_byte_length = 0;

  v8::Local<v8::DataView> GetDataView(v8::Isolate* isolate) {
    if (data_view.IsEmpty()) {
      const v8::HandleScope handle_scope(isolate);
      auto dv = v8::DataView::New(buffer.Get(isolate), 0, page_byte_length);
      data_view = v8::Global<v8::DataView>(isolate, dv);
    }
    return data_view.Get(isolate);
  }

  v8::Local<v8::BigUint64Array> GetBigUint64Array(v8::Isolate* isolate) {
    if (big_uint64_array.IsEmpty()) {
      const v8::HandleScope handle_scope(isolate);
      auto bu = v8::BigUint64Array::New(
          buffer.Get(isolate), 0, page_byte_length / sizeof(uint64_t));
      big_uint64_array = v8::Global<v8::BigUint64Array>(isolate, bu);
    }
    return big_uint64_array.Get(isolate);
  }
};
}  // namespace detail

inline v8::Local<v8::ArrayBuffer> ArenaSlotBase::GetArrayBuffer(
    v8::Isolate* isolate) const {
  DCHECK_NOT_NULL(page);
  auto* header = static_cast<detail::ArenaPageHeader*>(page);
  return header->buffer.Get(isolate);
}

inline v8::Local<v8::DataView> ArenaSlotBase::GetPageDataView(
    v8::Isolate* isolate) const {
  DCHECK_NOT_NULL(page);
  auto* header = static_cast<detail::ArenaPageHeader*>(page);
  return header->GetDataView(isolate);
}

inline v8::Local<v8::BigUint64Array> ArenaSlotBase::GetPageBigUint64Array(
    v8::Isolate* isolate) const {
  DCHECK_NOT_NULL(page);
  auto* header = static_cast<detail::ArenaPageHeader*>(page);
  return header->GetBigUint64Array(isolate);
}

}  // namespace node

#endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

#endif  // SRC_ALIASED_STRUCT_H_