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"
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
{
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
41 using RequestInterruptCallbackType
= std::function
<void(uint32_t)>;
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
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);
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
);
79 void Schedule(bool aAllowIdleDispatch
);
81 const char* GetName() { return mName
; }
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
);
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
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.
109 // The least duration worth calling the callback for during idle time.
110 TimeDuration mMinimumUsefulBudget
;
114 MayStopProcessingCallbackType mMayStopProcessing
;
115 RequestInterruptCallbackType mRequestInterrupt
;
117 RefPtr
<IdleTaskRunnerTask
> mTask
;
120 } // end of namespace mozilla.