Backed out 3 changesets (bug 1854934) for causing build bustages on widget/windows...
[gecko.git] / xpcom / threads / IdleTaskRunner.h
blob4052021f088aada1aab7f53b238a0def00b38b89
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/. */
7 #ifndef IdleTaskRunner_h
8 #define IdleTaskRunner_h
10 #include "mozilla/TimeStamp.h"
11 #include "nsIEventTarget.h"
12 #include "nsISupports.h"
13 #include "nsITimer.h"
14 #include <functional>
16 namespace mozilla {
18 class IdleTaskRunnerTask;
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)
29 // Return true if some meaningful work was done.
30 using CallbackType = std::function<bool(TimeStamp aDeadline)>;
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()>;
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)>;
43 public:
44 // An IdleTaskRunner has (up to) three phases:
46 // - (duration aStartDelay) waiting to run (aStartDelay can be zero)
48 // - (duration aMaxDelay) attempting to find a long enough amount of idle
49 // time, at least aMinimumUsefulBudget
51 // - overdue for idle time, run as soon as possible
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.
57 // All durations are in milliseconds.
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);
66 void Run();
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);
72 void SetTimer(TimeDuration aDelay, nsIEventTarget* aTarget);
74 // Update the minimum idle time that this callback would be invoked for.
75 void SetMinimumUsefulBudget(int64_t aMinimumUsefulBudget);
77 void Cancel();
79 void Schedule(bool aAllowIdleDispatch);
81 const char* GetName() { return mName; }
83 private:
84 explicit IdleTaskRunner(
85 const CallbackType& aCallback, const char* aRunnableName,
86 TimeDuration aStartDelay, TimeDuration aMaxDelay,
87 TimeDuration aMinimumUsefulBudget, bool aRepeating,
88 const MayStopProcessingCallbackType& aMayStopProcessing,
89 const RequestInterruptCallbackType& aRequestInterrupt);
90 ~IdleTaskRunner();
91 void CancelTimer();
92 void SetTimerInternal(TimeDuration aDelay);
94 nsCOMPtr<nsITimer> mTimer;
95 nsCOMPtr<nsITimer> mScheduleTimer;
96 CallbackType mCallback;
98 // Do not run until this time.
99 const mozilla::TimeStamp mStartTime;
101 // Wait this long for idle time before giving up and running a non-idle
102 // callback.
103 TimeDuration mMaxDelay;
105 // If running during idle time, the expected end of the current idle period.
106 // The null timestamp when the run is triggered by aMaxDelay instead of idle.
107 TimeStamp mDeadline;
109 // The least duration worth calling the callback for during idle time.
110 TimeDuration mMinimumUsefulBudget;
112 bool mRepeating;
113 bool mTimerActive;
114 MayStopProcessingCallbackType mMayStopProcessing;
115 RequestInterruptCallbackType mRequestInterrupt;
116 const char* mName;
117 RefPtr<IdleTaskRunnerTask> mTask;
120 } // end of namespace mozilla.
122 #endif