/* 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/. */

/*
 * Code to notify things that animate before a refresh, at an appropriate
 * refresh rate.  (Perhaps temporary, until replaced by compositor.)
 */

#ifndef nsRefreshDriver_h_
#define nsRefreshDriver_h_

#include "GeckoProfiler.h"  // for ProfileChunkedBuffer
#include "LayersTypes.h"
#include "mozilla/Attributes.h"
#include "mozilla/FlushType.h"
#include "mozilla/Maybe.h"
#include "mozilla/RenderingPhase.h"
#include "mozilla/TimeStamp.h"
#include "mozilla/UniquePtr.h"
#include "mozilla/WeakPtr.h"
#include "mozilla/layers/TransactionIdAllocator.h"
#include "nsClassHashtable.h"
#include "nsHashKeys.h"
#include "nsRefreshObservers.h"
#include "nsTArray.h"
#include "nsTHashSet.h"
#include "nsTObserverArray.h"
#include "nsThreadUtils.h"

class nsPresContext;

class imgIRequest;
class nsIRunnable;

struct DocumentFrameCallbacks;

namespace mozilla {
class AnimationEventDispatcher;
class PaintPendingHangAnnotator;
class PresShell;
class RefreshDriverTimer;
class Runnable;
class Task;

namespace dom {
class Document;
}

}  // namespace mozilla

class nsRefreshDriver final : public mozilla::layers::TransactionIdAllocator,
                              public nsARefreshObserver {
  using Document = mozilla::dom::Document;
  using TransactionId = mozilla::layers::TransactionId;
  using LogPresShellObserver = mozilla::LogPresShellObserver;

 public:
  explicit nsRefreshDriver(nsPresContext* aPresContext);
  ~nsRefreshDriver();

  /**
   * Methods for testing, exposed via nsIDOMWindowUtils.  See
   * nsIDOMWindowUtils.advanceTimeAndRefresh for description.
   */
  void AdvanceTimeAndRefresh(int64_t aMilliseconds);
  void RestoreNormalRefresh();
  void DoTick();
  bool IsTestControllingRefreshesEnabled() const {
    return mTestControllingRefreshes;
  }

  /**
   * Return the time of the most recent refresh.  This is intended to be
   * used by callers who want to start an animation now and want to know
   * what time to consider the start of the animation.  (This helps
   * ensure that multiple animations started during the same event off
   * the main event loop have the same start time.)
   */
  mozilla::TimeStamp MostRecentRefresh() const { return mMostRecentRefresh; }

  /**
   * Add / remove refresh observers.
   * RemoveRefreshObserver returns true if aObserver was found.
   *
   * The flush type affects:
   *   + the order in which the observers are notified (lowest flush
   *     type to highest, in order registered)
   *   + (in the future) which observers are suppressed when the display
   *     doesn't require current position data or isn't currently
   *     painting, and, correspondingly, which get notified when there
   *     is a flush during such suppression
   * and it must be FlushType::Style, or FlushType::Display.
   *
   * The refresh driver does NOT own a reference to these observers;
   * they must remove themselves before they are destroyed.
   *
   * The observer will be called even if there is no other activity.
   */
  void AddRefreshObserver(nsARefreshObserver* aObserver,
                          mozilla::FlushType aFlushType,
                          const char* aObserverDescription);
  bool RemoveRefreshObserver(nsARefreshObserver* aObserver,
                             mozilla::FlushType aFlushType);

  MOZ_CAN_RUN_SCRIPT void FlushLayoutOnPendingDocsAndFixUpFocus();

  /**
   * Add an observer that will be called after each refresh. The caller
   * must remove the observer before it is deleted. This does not trigger
   * refresh driver ticks.
   */
  void AddPostRefreshObserver(nsAPostRefreshObserver* aObserver);
  void AddPostRefreshObserver(mozilla::ManagedPostRefreshObserver*) = delete;
  void RemovePostRefreshObserver(nsAPostRefreshObserver* aObserver);
  void RemovePostRefreshObserver(mozilla::ManagedPostRefreshObserver*) = delete;

  /**
   * Add/Remove imgIRequest versions of observers.
   *
   * These are used for hooking into the refresh driver for
   * controlling animated images.
   *
   * @note The refresh driver owns a reference to these listeners.
   *
   * @note Technically, imgIRequest objects are not nsARefreshObservers, but
   * for controlling animated image repaint events, we subscribe the
   * imgIRequests to the nsRefreshDriver for notification of paint events.
   */
  void AddImageRequest(imgIRequest* aRequest);
  void RemoveImageRequest(imgIRequest* aRequest);
  void StartTimerForAnimatedImagesIfNeeded();
  void StopTimerForAnimatedImagesIfNeeded();

  /**
   * Marks that we're currently in the middle of processing user input.
   * Called by EventDispatcher when it's handling an input event.
   */
  void EnterUserInputProcessing() { mUserInputProcessingCount++; }
  void ExitUserInputProcessing() {
    MOZ_ASSERT(mUserInputProcessingCount > 0);
    mUserInputProcessingCount--;
  }

  /**
   * "Early Runner" runnables will be called as the first step when refresh
   * driver tick is triggered. Runners shouldn't keep other objects alive,
   * since it isn't guaranteed they will ever get called.
   */
  void AddEarlyRunner(nsIRunnable* aRunnable) {
    mEarlyRunners.AppendElement(aRunnable);
    EnsureTimerStarted();
  }

  // Remember whether our presshell's view manager needs a flush
  void SchedulePaint();
  bool IsPaintPending() const {
    return mRenderingPhasesNeeded.contains(mozilla::RenderingPhase::Paint);
  }

  // Returns true if a paint actually occurred.
  MOZ_CAN_RUN_SCRIPT bool PaintIfNeeded();

  /**
   * Schedule a frame visibility update "soon", subject to the heuristics and
   * throttling we apply to visibility updates.
   */
  void ScheduleFrameVisibilityUpdate() { mNeedToRecomputeVisibility = true; }

  /**
   * Tell the refresh driver that it is done driving refreshes and
   * should stop its timer and forget about its pres context.  This may
   * be called from within a refresh.
   */
  void Disconnect();

  bool IsFrozen() const { return mFreezeCount > 0; }

  bool IsThrottled() const { return mThrottled; }

  /**
   * Freeze the refresh driver.  It should stop delivering future
   * refreshes until thawed. Note that the number of calls to Freeze() must
   * match the number of calls to Thaw() in order for the refresh driver to
   * be un-frozen.
   */
  void Freeze();

  /**
   * Thaw the refresh driver.  If the number of calls to Freeze() matches the
   * number of calls to this function, the refresh driver should start
   * delivering refreshes again.
   */
  void Thaw();

  /**
   * Throttle or unthrottle the refresh driver.  This is done if the
   * corresponding presshell is hidden or shown.
   */
  void SetActivity(bool aIsActive);

  /**
   * Return the prescontext we were initialized with
   */
  nsPresContext* GetPresContext() const;

  void CreateVsyncRefreshTimer();

#ifdef DEBUG
  /**
   * Check whether the given observer is an observer for the given flush type
   */
  bool IsRefreshObserver(nsARefreshObserver* aObserver,
                         mozilla::FlushType aFlushType);
#endif

  /**
   * Default interval the refresh driver uses, in ms.
   */
  static int32_t DefaultInterval();

  /**
   * Returns 1.0 if a recent rate wasn't smaller than
   * DefaultInterval(). Otherwise return rate / DefaultInterval();
   * So the return value is (0-1].
   *
   */
  static double HighRateMultiplier();

  bool IsInRefresh() { return mInRefresh; }

  void SetIsResizeSuppressed() { mResizeSuppressed = true; }
  bool IsResizeSuppressed() const { return mResizeSuppressed; }

  // mozilla::layers::TransactionIdAllocator
  TransactionId GetTransactionId(bool aThrottle) override;
  TransactionId LastTransactionId() const override;
  void NotifyTransactionCompleted(TransactionId aTransactionId) override;
  void RevokeTransactionId(TransactionId aTransactionId) override;
  void ClearPendingTransactions() override;
  void ResetInitialTransactionId(TransactionId aTransactionId) override;
  mozilla::TimeStamp GetTransactionStart() override;
  mozilla::VsyncId GetVsyncId() override;
  mozilla::TimeStamp GetVsyncStart() override;

  bool IsWaitingForPaint(mozilla::TimeStamp aTime);
  void ScheduleAutoFocusFlush() {
    ScheduleRenderingPhase(mozilla::RenderingPhase::FlushAutoFocusCandidates);
  }

  // nsARefreshObserver
  NS_IMETHOD_(MozExternalRefCountType) AddRef(void) override {
    return TransactionIdAllocator::AddRef();
  }
  NS_IMETHOD_(MozExternalRefCountType) Release(void) override {
    return TransactionIdAllocator::Release();
  }
  virtual void WillRefresh(mozilla::TimeStamp aTime) override;

  /**
   * Compute the time when the currently active refresh driver timer
   * will start its next tick.
   *
   * Expects a non-null default value that is the upper bound of the
   * expected deadline. If the next expected deadline is later than
   * the default value, the default value is returned.
   *
   * If we're animating and we have skipped paints a time in the past
   * is returned.
   *
   * If aCheckType is AllVsyncListeners and we're in the parent process,
   * which doesn't have a RefreshDriver ticking, but some other process does
   * have, the return value is
   * (now + refreshrate - layout.idle_period.time_limit) as an approximation
   * when something will happen.
   * This can be useful check when parent process tries to avoid having too
   * long idle periods for example when it is sending input events to an
   * active child process.
   */
  enum IdleCheck { OnlyThisProcessRefreshDriver, AllVsyncListeners };
  static mozilla::TimeStamp GetIdleDeadlineHint(mozilla::TimeStamp aDefault,
                                                IdleCheck aCheckType);

  /**
   * It returns the expected timestamp of the next tick or nothing if the next
   * tick is missed.
   */
  static mozilla::Maybe<mozilla::TimeStamp> GetNextTickHint();

  static bool IsRegularRateTimerTicking();

  static void DispatchIdleTaskAfterTickUnlessExists(mozilla::Task* aTask);
  static void CancelIdleTask(mozilla::Task* aTask);

  void InitializeTimer() {
    MOZ_ASSERT(!mActiveTimer);
    EnsureTimerStarted();
  }

  bool HasPendingTick() const { return mActiveTimer; }

  void ScheduleRenderingPhases(mozilla::RenderingPhases aPhases) {
    mRenderingPhasesNeeded += aPhases;
    EnsureTimerStarted();
  }

  void ScheduleRenderingPhase(mozilla::RenderingPhase aPhase) {
    ScheduleRenderingPhases({aPhase});
  }

  void EnsureIntersectionObservationsUpdateHappens() {
    // This is enough to make sure that UpdateIntersectionObservations runs at
    // least once. This is presumably the intent of step 5 in [1]:
    //
    //     Schedule an iteration of the event loop in the root's browsing
    //     context.
    //
    // Though the wording of it is not quite clear to me...
    //
    // [1]:
    // https://w3c.github.io/IntersectionObserver/#dom-intersectionobserver-observe
    ScheduleRenderingPhase(
        mozilla::RenderingPhase::UpdateIntersectionObservations);
  }

  void EnsureViewTransitionOperationsHappen() {
    ScheduleRenderingPhase(mozilla::RenderingPhase::ViewTransitionOperations);
  }

  void EnsureAnimationUpdate() {
    ScheduleRenderingPhase(
        mozilla::RenderingPhase::UpdateAnimationsAndSendEvents);
  }

  void ScheduleMediaQueryListenerUpdate() {
    ScheduleRenderingPhase(
        mozilla::RenderingPhase::EvaluateMediaQueriesAndReportChanges);
  }

  // Register a composition payload that will be forwarded to the layer manager
  // if the current or upcoming refresh tick does a paint.
  // If no paint happens, the payload is discarded.
  // Should only be called on root refresh drivers.
  void RegisterCompositionPayload(
      const mozilla::layers::CompositionPayload& aPayload);

  enum class TickReasons : uint32_t {
    None = 0,
    HasObservers = 1 << 0,
    HasImageAnimations = 1 << 1,
    HasPendingRenderingSteps = 1 << 2,
    RootNeedsMoreTicksForUserInput = 1 << 3,
  };

  void AddForceNotifyContentfulPaintPresContext(nsPresContext* aPresContext);
  void FlushForceNotifyContentfulPaintPresContext();

  // Mark that we've just run a tick from vsync, used to throttle 'extra'
  // paints to one per vsync (see CanDoExtraTick).
  void FinishedVsyncTick() { mAttemptedExtraTickSinceLastVsync = false; }

  bool HasReasonsToTick() const;

 private:
  using RequestTable = nsTHashSet<RefPtr<imgIRequest>>;
  struct ImageStartData {
    ImageStartData() = default;

    mozilla::Maybe<mozilla::TimeStamp> mStartTime;
    RequestTable mEntries;
  };
  using ImageStartTable = nsClassHashtable<nsUint32HashKey, ImageStartData>;

  struct ObserverData {
    nsARefreshObserver* mObserver;
    const char* mDescription;
    mozilla::TimeStamp mRegisterTime;
    mozilla::MarkerInnerWindowId mInnerWindowId;
    mozilla::UniquePtr<mozilla::ProfileChunkedBuffer> mCause;
    mozilla::FlushType mFlushType;

    bool operator==(nsARefreshObserver* aObserver) const {
      return mObserver == aObserver;
    }
    operator RefPtr<nsARefreshObserver>() { return mObserver; }
  };
  using ObserverArray = nsTObserverArray<ObserverData>;
  void RunFullscreenSteps();

  MOZ_CAN_RUN_SCRIPT
  void RunVideoAndFrameRequestCallbacks(mozilla::TimeStamp aNowTime);
  MOZ_CAN_RUN_SCRIPT
  void RunVideoFrameCallbacks(const nsTArray<RefPtr<Document>>&,
                              mozilla::TimeStamp aNowTime);
  MOZ_CAN_RUN_SCRIPT
  void RunFrameRequestCallbacks(const nsTArray<RefPtr<Document>>&,
                                mozilla::TimeStamp aNowTime);
  void UpdateRemoteFrameEffects();
  void UpdateRelevancyOfContentVisibilityAutoFrames();
  MOZ_CAN_RUN_SCRIPT void PerformPendingViewTransitionOperations();
  void MaybeIncreaseMeasuredTicksSinceLoading();
  void EvaluateMediaQueriesAndReportChanges();

  enum class IsExtraTick {
    No,
    Yes,
  };

  // Helper for Tick, to call WillRefresh(aNowTime) on each entry in
  // mObservers[aIdx] and then potentially do some additional post-notification
  // work that's associated with the FlushType corresponding to aIdx.
  //
  // Returns true on success, or false if one of our calls has destroyed our
  // pres context (in which case our callsite Tick() should immediately bail).
  MOZ_CAN_RUN_SCRIPT
  bool TickObserverArray(uint32_t aIdx, mozilla::TimeStamp aNowTime);

  MOZ_CAN_RUN_SCRIPT_BOUNDARY
  void Tick(mozilla::VsyncId aId, mozilla::TimeStamp aNowTime,
            IsExtraTick aIsExtraTick = IsExtraTick::No);

  enum EnsureTimerStartedFlags {
    eNone = 0,
    eForceAdjustTimer = 1 << 0,
    eAllowTimeToGoBackwards = 1 << 1,
  };
  void EnsureTimerStarted(EnsureTimerStartedFlags aFlags = eNone);
  void StopTimer();

  void UpdateThrottledState();

  bool HasObservers() const;
  void AppendObserverDescriptionsToString(nsACString& aStr) const;
  // Note: This should only be called in the dtor of nsRefreshDriver.
  uint32_t ObserverCount() const;
  bool ComputeHasImageAnimations() const;
  bool ShouldKeepTimerRunningWhileWaitingForFirstContentfulPaint();
  bool ShouldKeepTimerRunningAfterPageLoad();
  ObserverArray& ArrayFor(mozilla::FlushType aFlushType);
  // Trigger a refresh immediately, if haven't been disconnected or frozen.
  void DoRefresh();

  // Starts pending image animations, and refreshes ongoing animations.
  void UpdateAnimatedImages(mozilla::TimeStamp aPreviousRefresh,
                            mozilla::TimeStamp aNowTime);

  TickReasons GetReasonsToTick() const;
  void AppendTickReasonsToString(TickReasons aReasons, nsACString& aStr) const;

  double GetRegularTimerInterval() const;
  static double GetThrottledTimerInterval();

  static mozilla::TimeDuration GetMinRecomputeVisibilityInterval();

  void FinishedWaitingForTransaction();

  /**
   * Returns true if we didn't tick on the most recent vsync, but we think
   * we could run one now instead in order to reduce latency.
   */
  bool CanDoCatchUpTick();
  /**
   * Returns true if we think it's possible to run an repeat tick (between
   * vsyncs) to hopefully replace the original tick's paint on the compositor.
   * We allow this sometimes for tick requests coming for user input handling
   * to reduce latency.
   */
  bool CanDoExtraTick();

  bool AtPendingTransactionLimit() {
    return mPendingTransactions.Length() == 2;
  }
  bool TooManyPendingTransactions() {
    return mPendingTransactions.Length() >= 2;
  }

  mozilla::RefreshDriverTimer* ChooseTimer();
  mozilla::RefreshDriverTimer* mActiveTimer;
  RefPtr<mozilla::RefreshDriverTimer> mOwnTimer;
  mozilla::UniquePtr<mozilla::ProfileChunkedBuffer> mRefreshTimerStartedCause;

  // nsPresContext passed in constructor and unset in Disconnect.
  mozilla::WeakPtr<nsPresContext> mPresContext;

  RefPtr<nsRefreshDriver> mRootRefresh;

  // The most recently allocated transaction id.
  TransactionId mNextTransactionId;
  AutoTArray<TransactionId, 3> mPendingTransactions;

  uint32_t mFreezeCount;
  uint32_t mUserInputProcessingCount = 0;

  // How long we wait between ticks for throttled (which generally means
  // non-visible) documents registered with a non-throttled refresh driver.
  const mozilla::TimeDuration mThrottledFrameRequestInterval;

  // How long we wait, at a minimum, before recomputing approximate frame
  // visibility information. This is a minimum because, regardless of this
  // interval, we only recompute visibility when we've seen a layout or style
  // flush since the last time we did it.
  const mozilla::TimeDuration mMinRecomputeVisibilityInterval;

  mozilla::UniquePtr<mozilla::ProfileChunkedBuffer> mPaintCause;

  bool mThrottled : 1;
  bool mNeedToRecomputeVisibility : 1;
  bool mTestControllingRefreshes : 1;
  bool mInRefresh : 1;

  // True if the refresh driver is suspended waiting for transaction
  // id's to be returned and shouldn't do any work during Tick().
  bool mWaitingForTransaction : 1;
  // True if Tick() was skipped because of mWaitingForTransaction and
  // we should schedule a new Tick immediately when resumed instead
  // of waiting until the next interval.
  bool mSkippedPaints : 1;

  // True if view managers should delay any resize request until the
  // next tick by the refresh driver. This flag will be reset at the
  // start of every tick.
  bool mResizeSuppressed : 1;

  // True if we may need to run any frame callback.
  bool mNeedToRunFrameRequestCallbacks : 1;

  // True if we're currently within the scope of Tick() handling a normal
  // (timer-driven) tick.
  bool mInNormalTick : 1;

  // True if we attempted an extra tick (see CanDoExtraTick) since the last
  // vsync and thus shouldn't allow another.
  bool mAttemptedExtraTickSinceLastVsync : 1;

  bool mHasExceededAfterLoadTickPeriod : 1;

  bool mHasImageAnimations : 1;

  bool mHasStartedTimerAtLeastOnce : 1;

  mozilla::UniquePtr<mozilla::PaintPendingHangAnnotator> mHangAnnotator;

  mozilla::TimeStamp mMostRecentRefresh;
  mozilla::TimeStamp mTickStart;
  mozilla::VsyncId mTickVsyncId;
  mozilla::TimeStamp mTickVsyncTime;
  mozilla::TimeStamp mNextThrottledFrameRequestTick;
  mozilla::TimeStamp mNextRecomputeVisibilityTick;
  mozilla::TimeStamp mBeforeFirstContentfulPaintTimerRunningLimit;

  // The "Update the rendering" phases we need to run on our documents.
  mozilla::EnumSet<mozilla::RenderingPhase, uint16_t> mRenderingPhasesNeeded;

  // Runs a single update the rendering phase, at once, rather than filtering
  // the docs as per spec.
  //
  // TODO(emilio): This should be removed, ideally.
  template <typename Callback>
  MOZ_CAN_RUN_SCRIPT void RunRenderingPhaseLegacy(mozilla::RenderingPhase,
                                                  Callback&&);

  using DocFilter = bool (*)(const Document&);

  // Runs a single update the rendering phase with the callback called for each
  // document, as per spec.
  template <typename Callback>
  MOZ_CAN_RUN_SCRIPT void RunRenderingPhase(mozilla::RenderingPhase, Callback&&,
                                            DocFilter = nullptr);

  // separate arrays for each flush type we support
  ObserverArray mObservers[3];
  nsTArray<mozilla::layers::CompositionPayload> mCompositionPayloads;
  RequestTable mRequests;
  ImageStartTable mStartTable;
  AutoTArray<nsCOMPtr<nsIRunnable>, 16> mEarlyRunners;
  nsTObserverArray<nsAPostRefreshObserver*> mPostRefreshObservers;

  // nsPresContexts which `NotifyContentfulPaint` have been called,
  // however the corresponding paint doesn't come from a regular
  // rendering steps(aka tick).
  //
  // For these nsPresContexts, we invoke
  // `FlushForceNotifyContentfulPaintPresContext` in the next tick
  // to force notify contentful paint, regardless whether the tick paints
  // or not.
  nsTArray<mozilla::WeakPtr<nsPresContext>>
      mForceNotifyContentfulPaintPresContexts;

  void BeginRefreshingImages(RequestTable& aEntries,
                             mozilla::TimeStamp aDesired);

  friend class mozilla::RefreshDriverTimer;

  static void Shutdown();
};

#endif /* !defined(nsRefreshDriver_h_) */