components/scheduler/child/task_queue.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_TASK_QUEUE_H_
   6 #define COMPONENTS_SCHEDULER_CHILD_TASK_QUEUE_H_
   7
   8 #include "base/single_thread_task_runner.h"
   9 #include "components/scheduler/scheduler_export.h"
  10
  11 namespace scheduler {
  12
  13 class SCHEDULER_EXPORT TaskQueue : public base::SingleThreadTaskRunner {
  14  public:
  15   TaskQueue() {}
  16
  17   // Post a delayed task at an absolute desired run time instead of a time
  18   // delta from the current time.
  19   virtual bool PostDelayedTaskAt(const tracked_objects::Location& from_here,
  20                                  const base::Closure& task,
  21                                  base::TimeTicks desired_run_time) = 0;
  22
  23   enum QueuePriority {
  24     // Queues with control priority will run before any other queue, and will
  25     // explicitly starve other queues. Typically this should only be used for
  26     // private queues which perform control operations.
  27     CONTROL_PRIORITY,
  28     // Queues with high priority will be selected preferentially over normal or
  29     // best effort queues. The selector will ensure that high priority queues
  30     // cannot completely starve normal priority queues.
  31     HIGH_PRIORITY,
  32     // Queues with normal priority are the default.
  33     NORMAL_PRIORITY,
  34     // Queues with best effort priority will only be run if all other queues are
  35     // empty. They can be starved by the other queues.
  36     BEST_EFFORT_PRIORITY,
  37     // Queues with this priority are never run.  Must be penultimate entry.
  38     DISABLED_PRIORITY,
  39     // Must be the last entry.
  40     QUEUE_PRIORITY_COUNT,
  41     FIRST_QUEUE_PRIORITY = CONTROL_PRIORITY,
  42   };
  43
  44   // Keep TaskQueue::PumpPolicyToString in sync with this enum.
  45   enum class PumpPolicy {
  46     // Tasks posted to an incoming queue with an AUTO pump policy will be
  47     // automatically scheduled for execution or transferred to the work queue
  48     // automatically.
  49     AUTO,
  50     // Tasks posted to an incoming queue with an AFTER_WAKEUP pump policy
  51     // will be scheduled for execution or transferred to the work queue
  52     // automatically but only after another queue has executed a task.
  53     AFTER_WAKEUP,
  54     // Tasks posted to an incoming queue with a MANUAL will not be
  55     // automatically scheduled for execution or transferred to the work queue.
  56     // Instead, the selector should call PumpQueue() when necessary to bring
  57     // in new tasks for execution.
  58     MANUAL,
  59     // Must be last entry.
  60     PUMP_POLICY_COUNT,
  61     FIRST_PUMP_POLICY = AUTO,
  62   };
  63
  64   // Keep TaskQueue::WakeupPolicyToString in sync with this enum.
  65   enum class WakeupPolicy {
  66     // Tasks run on a queue with CAN_WAKE_OTHER_QUEUES wakeup policy can
  67     // cause queues with the AFTER_WAKEUP PumpPolicy to be woken up.
  68     CAN_WAKE_OTHER_QUEUES,
  69     // Tasks run on a queue with DONT_WAKE_OTHER_QUEUES won't cause queues
  70     // with the AFTER_WAKEUP PumpPolicy to be woken up.
  71     DONT_WAKE_OTHER_QUEUES,
  72     // Must be last entry.
  73     WAKEUP_POLICY_COUNT,
  74     FIRST_WAKEUP_POLICY = CAN_WAKE_OTHER_QUEUES,
  75   };
  76
  77   enum class QueueState {
  78     // A queue in the EMPTY state is empty and has no tasks in either the
  79     // work or incoming task queue.
  80     EMPTY,
  81     // A queue in the NEEDS_PUMPING state has no tasks in the work task queue,
  82     // but has tasks in the incoming task queue which can be pumped to make them
  83     // runnable.
  84     NEEDS_PUMPING,
  85     // A queue in the HAS_WORK state has tasks in the work task queue which
  86     // are runnable.
  87     HAS_WORK,
  88   };
  89
  90   // Options for constructing a TaskQueue. Once set the |name|,
  91   // |should_monitor_quiescence| and |wakeup_policy| are immutable. The
  92   // |pump_policy| can be mutated with |SetPumpPolicy()|.
  93   struct Spec {
  94     // Note |name| must have application lifetime.
  95     explicit Spec(const char* name)
  96         : name(name),
  97           should_monitor_quiescence(false),
  98           pump_policy(TaskQueue::PumpPolicy::AUTO),
  99           wakeup_policy(TaskQueue::WakeupPolicy::CAN_WAKE_OTHER_QUEUES),
 100           should_notify_observers(true) {}
 101
 102     Spec SetShouldMonitorQuiescence(bool should_monitor) {
 103       should_monitor_quiescence = should_monitor;
 104       return *this;
 105     }
 106
 107     Spec SetPumpPolicy(PumpPolicy policy) {
 108       pump_policy = policy;
 109       return *this;
 110     }
 111
 112     Spec SetWakeupPolicy(WakeupPolicy policy) {
 113       wakeup_policy = policy;
 114       return *this;
 115     }
 116
 117     Spec SetShouldNotifyObservers(bool run_observers) {
 118       should_notify_observers = run_observers;
 119       return *this;
 120     }
 121
 122     const char* name;
 123     bool should_monitor_quiescence;
 124     TaskQueue::PumpPolicy pump_policy;
 125     TaskQueue::WakeupPolicy wakeup_policy;
 126     bool should_notify_observers;
 127   };
 128
 129   // Returns true if the queue priority is not
 130   // TaskQueueSelector::DISABLED_PRIORITY. NOTE this must be called on the
 131   // thread this TaskQueue was created by.
 132   virtual bool IsQueueEnabled() const = 0;
 133
 134   // Returns true if there no tasks in either the work or incoming task queue.
 135   // Note that this function involves taking a lock, so calling it has some
 136   // overhead. NOTE this must be called on the thread this TaskQueue was created
 137   // by.
 138   virtual bool IsQueueEmpty() const;
 139
 140   // Returns the QueueState. Note that this function involves taking a lock, so
 141   // calling it has some overhead.
 142   virtual QueueState GetQueueState() const = 0;
 143
 144   // Can be called on any thread.
 145   virtual const char* GetName() const = 0;
 146
 147   // Set the priority of the queue to |priority|. NOTE this must be called on
 148   // the thread this TaskQueue was created by.
 149   virtual void SetQueuePriority(QueuePriority priority) = 0;
 150
 151   // Set the pumping policy of the queue to |pump_policy|. NOTE this must be
 152   // called on the thread this TaskQueue was created by.
 153   virtual void SetPumpPolicy(PumpPolicy pump_policy) = 0;
 154
 155   // Reloads new tasks from the incoming queue into the work queue, regardless
 156   // of whether the work queue is empty or not. After this, the function ensures
 157   // that the tasks in the work queue, if any, are scheduled for execution.
 158   //
 159   // This function only needs to be called if automatic pumping is disabled.
 160   // By default automatic pumping is enabled for all queues. NOTE this must be
 161   // called on the thread this TaskQueue was created by.
 162   virtual void PumpQueue() = 0;
 163
 164  protected:
 165   ~TaskQueue() override {}
 166
 167   DISALLOW_COPY_AND_ASSIGN(TaskQueue);
 168 };
 169
 170 }  // namespace scheduler
 171
 172 #endif  // COMPONENTS_SCHEDULER_CHILD_TASK_QUEUE_H_