xpcom/threads/IdleTaskRunner.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef IdleTaskRunner_h
   8 #define IdleTaskRunner_h
   9
  10 #include "mozilla/TimeStamp.h"
  11 #include "nsIEventTarget.h"
  12 #include "nsISupports.h"
  13 #include "nsITimer.h"
  14 #include <functional>
  15
  16 namespace mozilla {
  17
  18 class IdleTaskRunnerTask;
  19
  20 // A general purpose repeating callback runner (it can be configured to a
  21 // one-time runner, too.) If it is running repeatedly, one has to either
  22 // explicitly Cancel() the runner or have MayStopProcessing() callback return
  23 // true to completely remove the runner.
  24 class IdleTaskRunner {
  25  public:
  26   friend class IdleTaskRunnerTask;
  27   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(IdleTaskRunner)
  28
  29   // Return true if some meaningful work was done.
  30   using CallbackType = std::function<bool(TimeStamp aDeadline)>;
  31
  32   // A callback for "stop processing" decision. Return true to
  33   // stop processing. This can be an alternative to Cancel() or
  34   // work together in different way.
  35   using MayStopProcessingCallbackType = std::function<bool()>;
  36
  37   // A callback to be invoked when an interrupt is requested
  38   // (eg during an idle activity when the user presses a key.)
  39   // The callback takes an "interrupt priority" value as its
  40   // sole parameter.
  41   using RequestInterruptCallbackType = std::function<void(uint32_t)>;
  42
  43  public:
  44   // An IdleTaskRunner has (up to) three phases:
  45   //
  46   //  - (duration aStartDelay) waiting to run (aStartDelay can be zero)
  47   //
  48   //  - (duration aMaxDelay) attempting to find a long enough amount of idle
  49   //    time, at least aMinimumUsefulBudget
  50   //
  51   //  - overdue for idle time, run as soon as possible
  52   //
  53   // If aRepeating is true, then aStartDelay applies only to the first run; the
  54   // second run will attempt to run in the first idle slice that is long
  55   // enough.
  56   //
  57   // All durations are in milliseconds.
  58   //
  59   static already_AddRefed<IdleTaskRunner> Create(
  60       const CallbackType& aCallback, const char* aRunnableName,
  61       TimeDuration aStartDelay, TimeDuration aMaxDelay,
  62       TimeDuration aMinimumUsefulBudget, bool aRepeating,
  63       const MayStopProcessingCallbackType& aMayStopProcessing,
  64       const RequestInterruptCallbackType& aRequestInterrupt = nullptr);
  65
  66   void Run();
  67
  68   // (Used by the task triggering code.) Record the end of the current idle
  69   // period, or null if not running during idle time.
  70   void SetIdleDeadline(mozilla::TimeStamp aDeadline);
  71
  72   // If the timer is already active, SetTimer doesn't do anything.
  73   void SetTimer(TimeDuration aDelay, nsIEventTarget* aTarget);
  74
  75   void ResetTimer(TimeDuration aDelay);
  76
  77   // Update the minimum idle time that this callback would be invoked for.
  78   void SetMinimumUsefulBudget(int64_t aMinimumUsefulBudget);
  79
  80   void Cancel();
  81
  82   void Schedule(bool aAllowIdleDispatch);
  83
  84   const char* GetName() { return mName; }
  85
  86  private:
  87   explicit IdleTaskRunner(
  88       const CallbackType& aCallback, const char* aRunnableName,
  89       TimeDuration aStartDelay, TimeDuration aMaxDelay,
  90       TimeDuration aMinimumUsefulBudget, bool aRepeating,
  91       const MayStopProcessingCallbackType& aMayStopProcessing,
  92       const RequestInterruptCallbackType& aRequestInterrupt);
  93   ~IdleTaskRunner();
  94   void CancelTimer();
  95   void SetTimerInternal(TimeDuration aDelay);
  96
  97   nsCOMPtr<nsITimer> mTimer;
  98   nsCOMPtr<nsITimer> mScheduleTimer;
  99   CallbackType mCallback;
 100
 101   // Do not run until this time.
 102   const mozilla::TimeStamp mStartTime;
 103
 104   // Wait this long for idle time before giving up and running a non-idle
 105   // callback.
 106   TimeDuration mMaxDelay;
 107
 108   // If running during idle time, the expected end of the current idle period.
 109   // The null timestamp when the run is triggered by aMaxDelay instead of idle.
 110   TimeStamp mDeadline;
 111
 112   // The least duration worth calling the callback for during idle time.
 113   TimeDuration mMinimumUsefulBudget;
 114
 115   bool mRepeating;
 116   bool mTimerActive;
 117   MayStopProcessingCallbackType mMayStopProcessing;
 118   RequestInterruptCallbackType mRequestInterrupt;
 119   const char* mName;
 120   RefPtr<IdleTaskRunnerTask> mTask;
 121 };
 122
 123 }  // end of namespace mozilla.
 124
 125 #endif