components/scheduler/child/idle_helper.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_SCHEDULER_CHILD_IDLE_HELPER_H_
   6 #define COMPONENTS_SCHEDULER_CHILD_IDLE_HELPER_H_
   7
   8 #include "base/message_loop/message_loop.h"
   9 #include "components/scheduler/child/cancelable_closure_holder.h"
  10 #include "components/scheduler/child/scheduler_helper.h"
  11 #include "components/scheduler/child/single_thread_idle_task_runner.h"
  12 #include "components/scheduler/child/task_queue_selector.h"
  13 #include "components/scheduler/scheduler_export.h"
  14
  15 namespace scheduler {
  16
  17 class SchedulerHelper;
  18
  19 // Common scheduler functionality for Idle tasks.
  20 class SCHEDULER_EXPORT IdleHelper
  21     : public base::MessageLoop::TaskObserver,
  22       public SingleThreadIdleTaskRunner::Delegate {
  23  public:
  24   // Used to by scheduler implementations to customize idle behaviour.
  25   class SCHEDULER_EXPORT Delegate {
  26    public:
  27     Delegate();
  28     virtual ~Delegate();
  29
  30     // If it's ok to enter a long idle period, return true.  Otherwise return
  31     // false and set next_long_idle_period_delay_out so we know when to try
  32     // again.
  33     virtual bool CanEnterLongIdlePeriod(
  34         base::TimeTicks now,
  35         base::TimeDelta* next_long_idle_period_delay_out) = 0;
  36
  37     // Signals that the Long Idle Period hasn't started yet because the system
  38     // isn't quiescent.
  39     virtual void IsNotQuiescent() = 0;
  40
  41     // Signals that we have started an Idle Period.
  42     virtual void OnIdlePeriodStarted() = 0;
  43
  44     // Signals that we have finished an Idle Period.
  45     virtual void OnIdlePeriodEnded() = 0;
  46
  47    private:
  48     DISALLOW_COPY_AND_ASSIGN(Delegate);
  49   };
  50
  51   // Keep IdleHelper::IdlePeriodStateToString in sync with this enum.
  52   enum class IdlePeriodState {
  53     NOT_IN_IDLE_PERIOD,
  54     IN_SHORT_IDLE_PERIOD,
  55     IN_LONG_IDLE_PERIOD,
  56     IN_LONG_IDLE_PERIOD_WITH_MAX_DEADLINE,
  57     IN_LONG_IDLE_PERIOD_PAUSED,
  58     // Must be the last entry.
  59     IDLE_PERIOD_STATE_COUNT,
  60     FIRST_IDLE_PERIOD_STATE = NOT_IN_IDLE_PERIOD,
  61   };
  62
  63   // The maximum length of an idle period.
  64   static const int kMaximumIdlePeriodMillis = 50;
  65
  66   // |helper| and |delegate| are not owned by IdleHelper object and must
  67   // outlive it.
  68   IdleHelper(
  69       SchedulerHelper* helper,
  70       Delegate* delegate,
  71       const char* tracing_category,
  72       const char* disabled_by_default_tracing_category,
  73       const char* idle_period_tracing_name,
  74       base::TimeDelta required_quiescence_duration_before_long_idle_period);
  75   ~IdleHelper() override;
  76
  77   // Returns the idle task runner. Tasks posted to this runner may be reordered
  78   // relative to other task types and may be starved for an arbitrarily long
  79   // time if no idle time is available.
  80   scoped_refptr<SingleThreadIdleTaskRunner> IdleTaskRunner();
  81
  82   // If |required_quiescence_duration_before_long_idle_period_| is zero then
  83   // immediately initiate a long idle period, otherwise check if any tasks have
  84   // run recently and if so, check again after a delay of
  85   // |required_quiescence_duration_before_long_idle_period_|.
  86   // Calling this function will end any previous idle period immediately, and
  87   // potentially again later if
  88   // |required_quiescence_duration_before_long_idle_period_| is non-zero.
  89   // NOTE EndIdlePeriod will disable the long idle periods.
  90   void EnableLongIdlePeriod();
  91
  92   // Start an idle period with a given idle period deadline.
  93   void StartIdlePeriod(IdlePeriodState new_idle_period_state,
  94                        base::TimeTicks now,
  95                        base::TimeTicks idle_period_deadline);
  96
  97   // This will end an idle period either started with StartIdlePeriod or
  98   // EnableLongIdlePeriod.
  99   void EndIdlePeriod();
 100
 101   // Returns true if a currently running idle task could exceed its deadline
 102   // without impacting user experience too much. This should only be used if
 103   // there is a task which cannot be pre-empted and is likely to take longer
 104   // than the largest expected idle task deadline. It should NOT be polled to
 105   // check whether more work can be performed on the current idle task after
 106   // its deadline has expired - post a new idle task for the continuation of the
 107   // work in this case.
 108   // Must be called from the thread this class was created on.
 109   bool CanExceedIdleDeadlineIfRequired() const;
 110
 111   // Returns the deadline for the current idle task.
 112   base::TimeTicks CurrentIdleTaskDeadline() const;
 113
 114   // SingleThreadIdleTaskRunner::Delegate implementation:
 115   void OnIdleTaskPosted() override;
 116   base::TimeTicks WillProcessIdleTask() override;
 117   void DidProcessIdleTask() override;
 118
 119   // base::MessageLoop::TaskObserver implementation:
 120   void WillProcessTask(const base::PendingTask& pending_task) override;
 121   void DidProcessTask(const base::PendingTask& pending_task) override;
 122
 123   IdlePeriodState SchedulerIdlePeriodState() const;
 124   static const char* IdlePeriodStateToString(IdlePeriodState state);
 125
 126  private:
 127   friend class BaseIdleHelperTest;
 128   friend class IdleHelperTest;
 129
 130   class State {
 131    public:
 132     State(SchedulerHelper* helper,
 133           Delegate* delegate,
 134           const char* tracing_category,
 135           const char* disabled_by_default_tracing_category,
 136           const char* idle_period_tracing_name);
 137     virtual ~State();
 138
 139     void UpdateState(IdlePeriodState new_state,
 140                      base::TimeTicks new_deadline,
 141                      base::TimeTicks optional_now);
 142     bool IsIdlePeriodPaused() const;
 143
 144     IdlePeriodState idle_period_state() const;
 145     base::TimeTicks idle_period_deadline() const;
 146
 147     void TraceIdleIdleTaskStart();
 148     void TraceIdleIdleTaskEnd();
 149
 150    private:
 151     void TraceEventIdlePeriodStateChange(IdlePeriodState new_state,
 152                                          bool new_running_idle_task,
 153                                          base::TraceTicks new_deadline,
 154                                          base::TraceTicks optional_now);
 155
 156     SchedulerHelper* helper_;  // NOT OWNED
 157     Delegate* delegate_;       // NOT OWNED
 158
 159     IdlePeriodState idle_period_state_;
 160     base::TimeTicks idle_period_deadline_;
 161
 162     base::TraceTicks idle_period_deadline_for_tracing_;
 163     base::TraceTicks last_idle_task_trace_time_;
 164     bool idle_period_trace_event_started_;
 165     bool running_idle_task_for_tracing_;
 166     const char* tracing_category_;
 167     const char* disabled_by_default_tracing_category_;
 168     const char* idle_period_tracing_name_;
 169
 170     DISALLOW_COPY_AND_ASSIGN(State);
 171   };
 172
 173   // The minimum duration of an idle period.
 174   static const int kMinimumIdlePeriodDurationMillis = 1;
 175
 176   // The minimum delay to wait between retrying to initiate a long idle time.
 177   static const int kRetryEnableLongIdlePeriodDelayMillis = 1;
 178
 179   // Returns the new idle period state for the next long idle period. Fills in
 180   // |next_long_idle_period_delay_out| with the next time we should try to
 181   // initiate the next idle period.
 182   IdlePeriodState ComputeNewLongIdlePeriodState(
 183       const base::TimeTicks now,
 184       base::TimeDelta* next_long_idle_period_delay_out);
 185
 186   bool ShouldWaitForQuiescence();
 187   void OnIdleTaskPostedOnMainThread();
 188   void UpdateLongIdlePeriodStateAfterIdleTask();
 189
 190   void SetIdlePeriodState(IdlePeriodState new_state,
 191                           base::TimeTicks new_deadline,
 192                           base::TimeTicks optional_now);
 193
 194   // Returns true if |state| represents being within an idle period state.
 195   static bool IsInIdlePeriod(IdlePeriodState state);
 196   // Returns true if |state| represents being within a long idle period state.
 197   static bool IsInLongIdlePeriod(IdlePeriodState state);
 198
 199   SchedulerHelper* helper_;  // NOT OWNED
 200   Delegate* delegate_;       // NOT OWNED
 201   scoped_refptr<TaskQueue> idle_queue_;
 202   scoped_refptr<SingleThreadIdleTaskRunner> idle_task_runner_;
 203
 204   CancelableClosureHolder enable_next_long_idle_period_closure_;
 205   CancelableClosureHolder on_idle_task_posted_closure_;
 206
 207   State state_;
 208
 209   base::TimeDelta required_quiescence_duration_before_long_idle_period_;
 210
 211   const char* disabled_by_default_tracing_category_;
 212
 213   base::WeakPtr<IdleHelper> weak_idle_helper_ptr_;
 214   base::WeakPtrFactory<IdleHelper> weak_factory_;
 215
 216   DISALLOW_COPY_AND_ASSIGN(IdleHelper);
 217 };
 218
 219 }  // namespace scheduler
 220
 221 #endif  // COMPONENTS_SCHEDULER_CHILD_IDLE_HELPER_H_