src/api/api-arguments.h

// Copyright 2016 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 V8_API_API_ARGUMENTS_H_
#define V8_API_API_ARGUMENTS_H_

#include "include/v8-template.h"
#include "src/base/small-vector.h"
#include "src/builtins/builtins-utils.h"
#include "src/execution/isolate.h"
#include "src/objects/slots.h"
#include "src/objects/visitors.h"

namespace v8 {
namespace internal {

// This class also serves as a side effects detection scope (JavaScript code
// execution). It is used for ensuring correctness of the interceptor callback
// implementations. The idea is that the interceptor callback that does not
// intercept an operation must not produce side effects. If the callback
// signals that it has handled the operation (by either returning a respective
// result or by throwing an exception) then the AcceptSideEffects() method
// must be called to "accept" the side effects that have happened during the
// lifetime of the PropertyCallbackArguments object.
class PropertyCallbackArguments final : public Relocatable {
 public:
  using T = PropertyCallbackInfo<Value>;
  using Super = CustomArguments<T>;
  static constexpr int kMandatoryArgsLength = T::kMandatoryArgsLength;
  static constexpr int kFullArgsLength = T::kFullArgsLength;
  static constexpr int kMandatoryApiArgsLength = T::kMandatoryApiArgsLength;
  static constexpr int kFullApiArgsLength = T::kFullApiArgsLength;

  static constexpr int kGetterApiArgsLength = T::kMandatoryApiArgsLength;
  static constexpr int kSetterApiArgsLength = T::kFullApiArgsLength;

  static constexpr int kFrameTypeIndex = T::kFrameTypeIndex;
  static constexpr int kCallbackInfoIndex = T::kCallbackInfoIndex;
  static constexpr int kHolderIndex = T::kHolderIndex;
  static constexpr int kIsolateIndex = T::kIsolateIndex;
  static constexpr int kReturnValueIndex = T::kReturnValueIndex;
  static constexpr int kShouldThrowOnErrorIndex = T::kShouldThrowOnErrorIndex;
  static constexpr int kPropertyKeyIndex = T::kPropertyKeyIndex;
  static constexpr int kValueIndex = T::kValueIndex;

  // Helper for converting Api arguments indices to [0..kFullApiArgsLength)
  // value.
  static constexpr uint32_t ApiArgIndex(uint32_t index) {
    DCHECK_GE(index, T::kFirstApiArgumentIndex);
    return index - T::kFirstApiArgumentIndex;
  }

  // This constructor leaves kPropertyKeyIndex, kReturnValueIndex and
  // kCallbackInfoIndex slots uninitialized in order to let them be
  // initialized by the subsequent CallXXX(..) and avoid double initialization.
  // As a consequence, there must be no GC call between this constructor and
  // CallXXX(..). In debug mode these slots are zapped, so GC should be able
  // to detect misuse of this object.
  inline PropertyCallbackArguments(Isolate* isolate, Tagged<JSObject> holder);
  inline PropertyCallbackArguments(Isolate* isolate, Tagged<JSObject> holder,
                                   Maybe<ShouldThrow> should_throw);
  inline ~PropertyCallbackArguments();

  // Don't copy PropertyCallbackArguments, because they would both have the
  // same prev_ pointer.
  PropertyCallbackArguments(const PropertyCallbackArguments&) = delete;
  PropertyCallbackArguments& operator=(const PropertyCallbackArguments&) =
      delete;

  // -------------------------------------------------------------------------
  // Accessor Callbacks

  // Returns the result of [[Get]] operation or throws an exception.
  // In case of exception empty handle is returned.
  // TODO(ishell, 328490288): stop returning empty handles.
  inline DirectHandle<JSAny> CallAccessorGetter(Isolate* isolate,
                                                DirectHandle<AccessorInfo> info,
                                                DirectHandle<Name> name);
  // Returns the result of [[Set]] operation or throws an exception.
  V8_WARN_UNUSED_RESULT
  inline bool CallAccessorSetter(Isolate* isolate,
                                 DirectHandle<AccessorInfo> info,
                                 DirectHandle<Name> name,
                                 DirectHandle<Object> value);

  // -------------------------------------------------------------------------
  // Named Interceptor Callbacks

  // Empty handle means that the request was not intercepted.
  // Pending exception handling should be done by the caller.
  inline DirectHandle<Object> CallNamedQuery(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      DirectHandle<Name> name);
  inline DirectHandle<JSAny> CallNamedGetter(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      DirectHandle<Name> name);

  // Calls Setter/Definer/Deleter callback and returns whether the request
  // was intercepted.
  // Pending exception handling and interpretation of the result should be
  // done by the caller using GetBooleanReturnValue(..).
  inline v8::Intercepted CallNamedSetter(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      DirectHandle<Name> name, DirectHandle<Object> value);
  inline v8::Intercepted CallNamedDefiner(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      DirectHandle<Name> name, const v8::PropertyDescriptor& desc);
  inline v8::Intercepted CallNamedDeleter(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      DirectHandle<Name> name);

  // Empty handle means that the request was not intercepted.
  // Pending exception handling should be done by the caller.
  inline Handle<JSAny> CallNamedDescriptor(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      DirectHandle<Name> name);
  // Returns JSArray-like object with property names or undefined.
  inline DirectHandle<JSObjectOrUndefined> CallNamedEnumerator(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor);

  // -------------------------------------------------------------------------
  // Indexed Interceptor Callbacks

  // Empty handle means that the request was not intercepted.
  // Pending exception handling should be done by the caller.
  inline DirectHandle<Object> CallIndexedQuery(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      uint32_t index);
  inline DirectHandle<JSAny> CallIndexedGetter(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      uint32_t index);

  // Calls Setter/Definer/Deleter callback and returns whether the request
  // was intercepted.
  // Pending exception handling and interpretation of the result should be
  // done by the caller using GetBooleanReturnValue(..).
  inline v8::Intercepted CallIndexedSetter(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      uint32_t index, DirectHandle<Object> value);
  inline v8::Intercepted CallIndexedDefiner(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      uint32_t index, const v8::PropertyDescriptor& desc);
  inline v8::Intercepted CallIndexedDeleter(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      uint32_t index);

  // Empty handle means that the request was not intercepted.
  // Pending exception handling should be done by the caller.
  inline Handle<JSAny> CallIndexedDescriptor(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor,
      uint32_t index);
  // Returns JSArray-like object with property names or undefined.
  inline DirectHandle<JSObjectOrUndefined> CallIndexedEnumerator(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor);

  // Pending exception handling should be done by the caller.
  inline uint32_t CallIndexedIndexOf(Isolate* isolate,
                                     DirectHandle<InterceptorInfo> interceptor,
                                     DirectHandle<Object> value,
                                     uint32_t start_index, uint32_t end_index,
                                     uint32_t* in_out_length);

  // Pending exception handling should be done by the caller.
  inline DirectHandle<JSAny> CallIndexedIterableToList(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor);

  // Accept potential JavaScript side effects that might occur during life
  // time of this object.
  inline void AcceptSideEffects() {
#ifdef DEBUG
    javascript_execution_counter_ = 0;
#endif  // DEBUG
  }

  // Converts the result of Setter/Definer/Deleter interceptor callback to
  // Maybe<InterceptorResult>.
  // Currently, in certain scenarios the actual boolean result returned by
  // the Setter/Definer operation is ignored and thus we don't need to process
  // the actual return value.
  inline Maybe<InterceptorResult> GetBooleanReturnValue(
      Isolate* isolate, v8::Intercepted intercepted,
      const char* callback_kind_for_error_message,
      bool ignore_return_value = false);

  // TODO(ishell): cleanup this hack by embedding the PropertyCallbackInfo
  // into PropertyCallbackArguments object.
  template <typename T>
  const v8::PropertyCallbackInfo<T>& GetPropertyCallbackInfo() {
    return *(reinterpret_cast<PropertyCallbackInfo<T>*>(&values_[0]));
  }

  // Forwards ShouldThrowOnError() request to the underlying
  // v8::PropertyCallbackInfo<> object.
  bool ShouldThrowOnError() {
    return GetPropertyCallbackInfo<Value>().ShouldThrowOnError();
  }

  // Returns AccessorInfo stored in v8::PropertyCallbackInfo<T>.
  template <typename T>
  static DirectHandle<AccessorInfo> GetAccessorInfo(
      const PropertyCallbackInfo<T>& info) {
    return Cast<AccessorInfo>(
        DirectHandle<Object>::FromSlot(&info.args_[kCallbackInfoIndex]));
  }

  // Returns InterceptorInfo stored in v8::PropertyCallbackInfo<T>.
  template <typename T>
  static DirectHandle<InterceptorInfo> GetInterceptorInfo(
      const PropertyCallbackInfo<T>& info) {
    return Cast<InterceptorInfo>(
        DirectHandle<Object>::FromSlot(&info.args_[kCallbackInfoIndex]));
  }

  // Returns whether given v8::PropertyCallbackInfo<T> object is named/indexed.
  template <typename T>
  static bool IsNamed(const PropertyCallbackInfo<T>& info) {
    return info.IsNamed();
  }

  // Returns property name stored in v8::PropertyCallbackInfo<T> (for named
  // accessors/interceptors).
  template <typename T>
  static DirectHandle<Name> GetPropertyName(
      const PropertyCallbackInfo<T>& info) {
    DCHECK(info.IsNamed());
    return Cast<Name>(
        DirectHandle<Object>::FromSlot(&info.args_[kPropertyKeyIndex]));
  }

  // Returns property index stored in v8::PropertyCallbackInfo<T> (for indexed
  // interceptors).
  template <typename T>
  static uint32_t GetPropertyIndex(const PropertyCallbackInfo<T>& info) {
    DCHECK(!info.IsNamed());
    return static_cast<uint32_t>(info.args_[kPropertyKeyIndex]);
  }

  // Returns true if it's an arguments object for named callback, otherwise
  // it's one for an indexed callback.
  inline bool is_named() const;

  // Set property key and a respective frame type (named vs. indexed).
  inline void set_property_key(Tagged<Name> name);
  inline void set_property_key(uint32_t index);

  inline DirectHandle<JSObject> holder() const;

 private:
  inline void Initialize(Isolate* isolate, Tagged<JSObject> holder);
  // Returns JSArray-like object with property names or undefined.
  inline DirectHandle<JSObjectOrUndefined> CallPropertyEnumerator(
      Isolate* isolate, DirectHandle<InterceptorInfo> interceptor);

  void IterateInstance(RootVisitor* v) override;

  template <typename V>
  Handle<V> GetReturnValue() const;

  inline FullObjectSlot slot_at(int index) const {
    // This allows index == kFullArgsLength so "one past the end" slots
    // can be retrieved for iterating purposes.
    DCHECK_LE(static_cast<unsigned>(index),
              static_cast<unsigned>(kFullArgsLength));
    return FullObjectSlot(values_ + index);
  }

#ifdef DEBUG
  // Used for checking that the way this object was constructed matches the
  // following CallXxx(..).
  const bool is_setter_definer_deleter_;

  // This stores current value of Isolate::javascript_execution_counter().
  // It's used for detecting whether JavaScript code was executed between
  // PropertyCallbackArguments's constructor and destructor.
  uint32_t javascript_execution_counter_ = 0;
#endif  // DEBUG

  Address values_[kFullArgsLength];
};

class FunctionCallbackArguments : public Relocatable {
 public:
  using T = FunctionCallbackInfo<Value>;
  using Super = CustomArguments<T>;
  static constexpr int kArgsLength = T::kArgsLength;

  // Frame arguments block, the values are located on stack in the frame.
  static constexpr int kArgcIndex = T::kArgcIndex;
  static constexpr int kNewTargetIndex = T::kNewTargetIndex;
  static constexpr int kFrameSPIndex = T::kFrameSPIndex;
  static constexpr int kFrameTypeIndex = T::kFrameTypeIndex;

  // Api arguments block, the values are located on stack right above PC.
  static constexpr int kIsolateIndex = T::kIsolateIndex;
  static constexpr int kReturnValueIndex = T::kReturnValueIndex;
  static constexpr int kContextIndex = T::kContextIndex;
  static constexpr int kTargetIndex = T::kTargetIndex;
  static constexpr int kApiArgsLength = T::kApiArgsLength;

  // JS arguments block, follows Api arguments.
  static constexpr int kReceiverIndex = T::kReceiverIndex;
  static constexpr int kFirstJSArgumentIndex = T::kFirstJSArgumentIndex;

  // Helper for converting Api arguments indices to [0..kApiArgsLength) value.
  static constexpr uint32_t ApiArgIndex(uint32_t index) {
    DCHECK_GE(index, T::kFirstApiArgumentIndex);
    return index - T::kFirstApiArgumentIndex;
  }

  // Arguments for [[Call]] operation.
  template <typename ArgT>
  inline FunctionCallbackArguments(Isolate* isolate,
                                   Tagged<FunctionTemplateInfo> target,
                                   Tagged<Object> receiver,
                                   const base::Vector<const ArgT> args);
  // Arguments for [[Construct]] operation.
  template <typename ArgT>
  inline FunctionCallbackArguments(Isolate* isolate,
                                   Tagged<FunctionTemplateInfo> target,
                                   Tagged<HeapObject> new_target,
                                   Tagged<Object> receiver,
                                   const base::Vector<const ArgT> args);
  inline ~FunctionCallbackArguments();

  // Performs [[Call]] of [[Construct]] operation for a given function
  // and new_target.
  // Exception is supposed to be checked by the caller.
  // It explicitly returns raw value in order to enforce the caller to create
  // a handle if necessary.
  inline Tagged<JSAny> CallOrConstruct(Isolate* isolate,
                                       Tagged<FunctionTemplateInfo> function,
                                       bool is_construct);

  // Unofficial way of getting target FunctionTemplateInfo from
  // v8::FunctionCallbackInfo<T>.
  template <typename T>
  static Tagged<Object> GetTarget(const FunctionCallbackInfo<T>& info) {
    return Tagged<Object>(info.values_[kTargetIndex]);
  }

 private:
  template <bool is_construct, typename ArgT>
    requires(std::is_same_v<ArgT, DirectHandle<Object>> ||
             std::is_same_v<ArgT, Address>)
  inline void Initialize(Isolate* isolate, Tagged<FunctionTemplateInfo> target,
                         Tagged<Object> new_target, Tagged<Object> receiver,
                         const base::Vector<const ArgT> args);

  inline FullObjectSlot slot_at(uint32_t index) const {
    // Shift index to accommodate for unconditionally allocated "optional" part.
    index += T::kOptionalArgsLength;
    // This allows index == values_.size() so "one past the end" slots
    // can be retrieved for iterating purposes.
    DCHECK_LE(index, values_.size());
    // Don't use operator[] because it doesn't allow one past end index.
    return FullObjectSlot(&values_.data()[index]);
  }

  void IterateInstance(RootVisitor* v) override;

  // This default size is enough for passing up to 4 JS arguments.
  base::SmallVector<Address, 16> values_;
};

static_assert(BuiltinArguments::kNumExtraArgs ==
              BuiltinExitFrameConstants::kNumExtraArgs);
static_assert(BuiltinArguments::kNumExtraArgsWithReceiver ==
              BuiltinExitFrameConstants::kNumExtraArgsWithReceiver);

}  // namespace internal
}  // namespace v8

#endif  // V8_API_API_ARGUMENTS_H_