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