/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef debugger_Frame_h
#define debugger_Frame_h

#include "mozilla/Maybe.h"   // for Maybe
#include "mozilla/Range.h"   // for Range
#include "mozilla/Result.h"  // for Result

#include <stddef.h>  // for size_t

#include "NamespaceImports.h"   // for Value, MutableHandleValue, HandleObject
#include "debugger/DebugAPI.h"  // for ResumeMode
#include "debugger/Debugger.h"  // for ResumeMode, Handler, Debugger
#include "gc/Barrier.h"         // for HeapPtr
#include "vm/FrameIter.h"       // for FrameIter
#include "vm/JSObject.h"        // for JSObject
#include "vm/NativeObject.h"    // for NativeObject
#include "vm/Stack.h"           // for AbstractFramePtr

struct JS_PUBLIC_API JSContext;

namespace js {

class AbstractGeneratorObject;
class GlobalObject;

/*
 * An OnStepHandler represents a handler function that is called when a small
 * amount of progress is made in a frame.
 */
struct OnStepHandler : Handler {
  /*
   * If we have made a small amount of progress in a frame, this method is
   * called with the frame as argument. If succesful, this method should
   * return true, with `resumeMode` and `vp` set to a resumption value
   * specifiying how execution should continue.
   */
  virtual bool onStep(JSContext* cx, Handle<DebuggerFrame*> frame,
                      ResumeMode& resumeMode, MutableHandleValue vp) = 0;
};

class ScriptedOnStepHandler final : public OnStepHandler {
 public:
  explicit ScriptedOnStepHandler(JSObject* object);
  virtual JSObject* object() const override;
  virtual void hold(JSObject* owner) override;
  virtual void drop(JS::GCContext* gcx, JSObject* owner) override;
  virtual void trace(JSTracer* tracer) override;
  virtual size_t allocSize() const override;
  virtual bool onStep(JSContext* cx, Handle<DebuggerFrame*> frame,
                      ResumeMode& resumeMode, MutableHandleValue vp) override;

 private:
  const HeapPtr<JSObject*> object_;
};

/*
 * An OnPopHandler represents a handler function that is called just before a
 * frame is popped.
 */
struct OnPopHandler : Handler {
  /*
   * The given `frame` is about to be popped; `completion` explains why.
   *
   * When this method returns true, it must set `resumeMode` and `vp` to a
   * resumption value specifying how execution should continue.
   *
   * When this method returns false, it should set an exception on `cx`.
   */
  virtual bool onPop(JSContext* cx, Handle<DebuggerFrame*> frame,
                     const Completion& completion, ResumeMode& resumeMode,
                     MutableHandleValue vp) = 0;
};

class ScriptedOnPopHandler final : public OnPopHandler {
 public:
  explicit ScriptedOnPopHandler(JSObject* object);
  virtual JSObject* object() const override;
  virtual void hold(JSObject* owner) override;
  virtual void drop(JS::GCContext* gcx, JSObject* owner) override;
  virtual void trace(JSTracer* tracer) override;
  virtual size_t allocSize() const override;
  virtual bool onPop(JSContext* cx, Handle<DebuggerFrame*> frame,
                     const Completion& completion, ResumeMode& resumeMode,
                     MutableHandleValue vp) override;

 private:
  const HeapPtr<JSObject*> object_;
};

enum class DebuggerFrameType { Eval, Global, Call, Module, WasmCall };

enum class DebuggerFrameImplementation { Interpreter, Baseline, Ion, Wasm };

class DebuggerArguments : public NativeObject {
 public:
  static const JSClass class_;

  static DebuggerArguments* create(JSContext* cx, HandleObject proto,
                                   Handle<DebuggerFrame*> frame);

 private:
  enum { FRAME_SLOT };

  static const unsigned RESERVED_SLOTS = 1;
};

class DebuggerFrame : public NativeObject {
  friend class DebuggerArguments;
  friend class ScriptedOnStepHandler;
  friend class ScriptedOnPopHandler;

 public:
  static const JSClass class_;

  enum {
    FRAME_ITER_SLOT = 0,
    OWNER_SLOT,
    ARGUMENTS_SLOT,
    ONSTEP_HANDLER_SLOT,
    ONPOP_HANDLER_SLOT,

    // If this is a frame for a generator call, and the generator object has
    // been created (which doesn't happen until after default argument
    // evaluation and destructuring), then this is a PrivateValue pointing to a
    // GeneratorInfo struct that points to the call's AbstractGeneratorObject.
    // This allows us to implement Debugger.Frame methods even while the call is
    // suspended, and we have no FrameIter::Data.
    //
    // While Debugger::generatorFrames maps an AbstractGeneratorObject to its
    // Debugger.Frame, this link represents the reverse relation, from a
    // Debugger.Frame to its generator object. This slot is set if and only if
    // there is a corresponding entry in generatorFrames.
    GENERATOR_INFO_SLOT,

    // This is an AbstractFramePtr pointing at a wasm::DebugFrame that is on a
    // wasm::ContStack (see "Wasm Stack Switching" in WasmStacks.cpp).
    //
    // We use this in place of FRAME_ITER_SLOT when a debug frame is on a
    // wasm::ContStack because the stack may be suspended which will invalidate
    // any FrameIter pointing at it (cached JitActivation's are no longer
    // valid).
    //
    // Instead we lazily create a FrameIter when the stack owning this frame is
    // active, or else return !isOnStack() which prevents the debugger from
    // asking for a FrameIter.
    WASM_CONT_FRAME_PTR_SLOT,

    RESERVED_SLOTS,
  };

  void trace(JSTracer* trc);

  static NativeObject* initClass(JSContext* cx, Handle<GlobalObject*> global,
                                 HandleObject dbgCtor);
  static DebuggerFrame* create(JSContext* cx, HandleObject proto,
                               Handle<NativeObject*> debugger,
                               const FrameIter* maybeIter,
                               Handle<AbstractGeneratorObject*> maybeGenerator);

  [[nodiscard]] static bool getArguments(
      JSContext* cx, Handle<DebuggerFrame*> frame,
      MutableHandle<DebuggerArguments*> result);
  [[nodiscard]] static bool getCallee(JSContext* cx,
                                      Handle<DebuggerFrame*> frame,
                                      MutableHandle<DebuggerObject*> result);
  [[nodiscard]] static bool getIsConstructing(JSContext* cx,
                                              Handle<DebuggerFrame*> frame,
                                              bool& result);
  [[nodiscard]] static bool getEnvironment(
      JSContext* cx, Handle<DebuggerFrame*> frame,
      MutableHandle<DebuggerEnvironment*> result);
  [[nodiscard]] static bool getOffset(JSContext* cx,
                                      Handle<DebuggerFrame*> frame,
                                      size_t& result);
  [[nodiscard]] static bool getOlder(JSContext* cx,
                                     Handle<DebuggerFrame*> frame,
                                     MutableHandle<DebuggerFrame*> result);
  [[nodiscard]] static bool getAsyncPromise(
      JSContext* cx, Handle<DebuggerFrame*> frame,
      MutableHandle<DebuggerObject*> result);
  [[nodiscard]] static bool getOlderSavedFrame(
      JSContext* cx, Handle<DebuggerFrame*> frame,
      MutableHandle<SavedFrame*> result);
  [[nodiscard]] static bool getThis(JSContext* cx, Handle<DebuggerFrame*> frame,
                                    MutableHandleValue result);
  static DebuggerFrameType getType(JSContext* cx, Handle<DebuggerFrame*> frame);
  static DebuggerFrameImplementation getImplementation(
      Handle<DebuggerFrame*> frame);
  [[nodiscard]] static bool setOnStepHandler(JSContext* cx,
                                             Handle<DebuggerFrame*> frame,
                                             UniquePtr<OnStepHandler> handler);

  [[nodiscard]] static JS::Result<Completion> eval(
      JSContext* cx, Handle<DebuggerFrame*> frame,
      mozilla::Range<const char16_t> chars, HandleObject bindings,
      const EvalOptions& options);

  [[nodiscard]] static DebuggerFrame* check(JSContext* cx, HandleValue thisv);

  bool isOnStack(JSContext* cx) const;
  bool isOnStackOrSuspendedWasmStack() const;

  // True if this frame is on a wasm::ContStack (has WASM_CONT_FRAME_PTR_SLOT
  // set). Note this does not imply the frame is currently suspended.
  bool isWasmContFrame() const;

  // True if this frame is a suspended generator/async frame, i.e. it has
  // generator info and the generator object reports itself as suspended. This
  // only covers JS generator/async suspension, not wasm continuations; see
  // isSuspendedWasmFrame() for those, and isSuspended() for either.
  bool isSuspendedGeneratorFrame() const;

  // True if this frame is a wasm continuation that is currently suspended (e.g.
  // a JSPI continuation waiting on a promise) and may be resumed later. Unlike
  // isSuspendedGeneratorFrame(), which only covers generator/async suspension,
  // this covers wasm stack-switching continuations.
  bool isSuspendedWasmFrame(JSContext* cx) const;

  // True if this frame is suspended in any sense, i.e. it is either a suspended
  // generator/async frame or a suspended-resumable wasm continuation. A frame
  // that is neither on-stack nor suspended is terminated.
  bool isSuspended(JSContext* cx) const;

  OnStepHandler* onStepHandler() const;
  OnPopHandler* onPopHandler() const;
  void setOnPopHandler(JSContext* cx, OnPopHandler* handler);

  inline bool hasGeneratorInfo() const;

  // If hasGeneratorInfo(), return an direct cross-compartment reference to this
  // Debugger.Frame's generator object.
  AbstractGeneratorObject& unwrappedGenerator() const;

#ifdef DEBUG
  JSScript* generatorScript() const;
#endif

  /*
   * Associate the generator object genObj with this Debugger.Frame. This
   * association allows the Debugger.Frame to track the generator's execution
   * across suspensions and resumptions, and to implement some methods even
   * while the generator is suspended.
   *
   * The context `cx` must be in the Debugger.Frame's realm, and `genObj` must
   * be in a debuggee realm.
   *
   * Technically, the generator activation need not actually be on the stack
   * right now; it's okay to call this method on a Debugger.Frame that has no
   * ScriptFrameIter::Data at present. However, this function has no way to
   * verify that genObj really is the generator associated with the call for
   * which this Debugger.Frame was originally created, so it's best to make the
   * association while the call is on the stack, and the relationships are easy
   * to discern.
   */
  [[nodiscard]] static bool setGeneratorInfo(
      JSContext* cx, Handle<DebuggerFrame*> frame,
      Handle<AbstractGeneratorObject*> genObj);

  /*
   * Undo the effects of a prior call to setGenerator.
   *
   * If provided, owner must be the Debugger to which this Debugger.Frame
   * belongs; remove this frame's entry from its generatorFrames map, and clean
   * up its cross-compartment wrapper table entry. The owner must be passed
   * unless this method is being called from the Debugger.Frame's finalizer. (In
   * that case, the owner is not reliably available, and is not actually
   * necessary.)
   *
   * If maybeGeneratorFramesEnum is non-null, use it to remove this frame's
   * entry from the Debugger's generatorFrames weak map. In this case, this
   * function will not otherwise disturb generatorFrames. Passing the enum
   * allows this function to be used while iterating over generatorFrames.
   */
  void clearGeneratorInfo(JS::GCContext* gcx);

  /*
   * Called after a generator/async frame is resumed, before exposing this
   * Debugger.Frame object to any hooks.
   */
  bool resume(const FrameIter& iter);

  /*
   * Called when JS PI sets aside the cont stack frames.
   */
  void suspendWasmFrame(JS::GCContext* gcx);

  bool hasAnyHooks() const;

  Debugger* owner() const;

 private:
  static const JSClassOps classOps_;

  static const JSPropertySpec properties_[];
  static const JSFunctionSpec methods_[];

  static void finalize(JS::GCContext* gcx, JSObject* obj);

  static AbstractFramePtr getReferent(Handle<DebuggerFrame*> frame);
  [[nodiscard]] static bool requireScriptReferent(JSContext* cx,
                                                  Handle<DebuggerFrame*> frame);

  [[nodiscard]] static bool construct(JSContext* cx, unsigned argc, Value* vp);

  struct CallData;

  [[nodiscard]] bool incrementStepperCounter(JSContext* cx,
                                             AbstractFramePtr referent);
  [[nodiscard]] bool incrementStepperCounter(JSContext* cx,
                                             HandleScript script);
  void decrementStepperCounter(JS::GCContext* gcx, JSScript* script);
  void decrementStepperCounter(JS::GCContext* gcx, AbstractFramePtr referent);

  FrameIter::Data* frameIterData() const;
  void setFrameIterData(FrameIter::Data*);
  void freeFrameIterData(JS::GCContext* gcx);

 public:
  FrameIter getFrameIter(JSContext* cx);

  void terminate(JS::GCContext* gcx, AbstractFramePtr frame);
  void onGeneratorClosed(JS::GCContext* gcx);
  void suspendGeneratorFrame(JS::GCContext* gcx);

  [[nodiscard]] bool replaceFrameIterData(JSContext* cx, const FrameIter&);

  class GeneratorInfo;
  inline GeneratorInfo* generatorInfo() const;
};

} /* namespace js */

#endif /* debugger_Frame_h */