TaskScheduler: Change Sequence::PeekTask to Sequence::TakeTask.

base/task_scheduler/sequence.h

Index: base/task_scheduler/sequence.h
diff --git a/base/task_scheduler/sequence.h b/base/task_scheduler/sequence.h
index 8717336080e623dfde5ce8e5acc108ebcc9e61c0..6741e854bfe51093c6bf585c7603f8de846f39a9 100644
--- a/base/task_scheduler/sequence.h
+++ b/base/task_scheduler/sequence.h
@@ -22,7 +22,14 @@
 namespace base {
 namespace internal {
 
-// A sequence holds tasks that must be executed in posting order.
+// A Sequence holds tasks that must be executed in posting order.

[robliao, 2016/10/07 20:57:11]

A Sequence holds slots each containing up to a single task that must be executed
in posting order.

[fdoray, 2016/10/11 12:29:19]

Done.

+//
+// PushTask() adds a task in a new slot at the end of the Sequence. TakeTask()

[robliao, 2016/10/07 20:57:12]

This duplicates the method comments below. I would remove this.

[fdoray, 2016/10/11 12:29:19]

Done.

+// transfers ownership of the task in the front slot of the Sequence to the
+// caller, leaving the slot empty. Pop() removes the empty slot in front of the
+// Sequence.
+//
+// In comments below, an "empty Sequence" is a Sequence with no slot.
 //
 // Note: there is a known refcounted-ownership cycle in the Scheduler
 // architecture: Sequence -> Task -> TaskRunner -> Sequence -> ...
@@ -41,20 +48,27 @@ class BASE_EXPORT Sequence : public RefCountedThreadSafe<Sequence> {
  public:
   Sequence();
 
-  // Adds |task| at the end of the sequence's queue. Returns true if the
-  // sequence was empty before this operation.
+  // Adds |task| in a new slot at the end of the Sequence. Returns true if the
+  // Sequence was empty before this operation.
   bool PushTask(std::unique_ptr<Task> task);
 
-  // Returns the task in front of the sequence's queue, if any.
-  const Task* PeekTask() const;
+  // Transfers ownership of the Task in the front slot of the Sequence to the
+  // caller. The front slot of the Sequence will be empty until Pop() is

[robliao, 2016/10/07 20:57:12]

Might be clearer to say the "front slot of the Sequence will be nullptr and
remain until Pop()"

[fdoray, 2016/10/11 12:29:19]

Done.

+  // invoked. Cannot be called on an empty Sequence or a Sequence whose front
+  // slot is already empty.
+  std::unique_ptr<Task> TakeTask();
+
+  // Returns the TaskTraits of the Task in front of the Sequence. Cannot be
+  // called on an empty Sequence or on a Sequence whose front slot is empty.
+  TaskTraits PeekTaskTraits() const;
 
-  // Removes the task in front of the sequence's queue. Returns true if the
-  // sequence is empty after this operation. Cannot be called on an empty
-  // sequence.
-  bool PopTask();
+  // Removes the front slot of the Sequence. The front slot must have been
+  // emptied by TakeTask() before this is called. Cannot be called on an empty
+  // Sequence. Returns true if the Sequence is empty after this operation.
+  bool Pop();
 
-  // Returns a SequenceSortKey representing the priority of the sequence. Cannot
-  // be called on an empty sequence.
+  // Returns a SequenceSortKey representing the priority of the Sequence. Cannot
+  // be called on an empty Sequence.
   SequenceSortKey GetSortKey() const;
 
   // Returns a token that uniquely identifies this Sequence.
@@ -72,7 +86,7 @@ class BASE_EXPORT Sequence : public RefCountedThreadSafe<Sequence> {
   // Queue of tasks to execute.
   std::queue<std::unique_ptr<Task>> queue_;
 
-  // Number of tasks contained in the sequence for each priority.
+  // Number of tasks contained in the Sequence for each priority.
   size_t num_tasks_per_priority_[static_cast<int>(TaskPriority::HIGHEST) + 1] =
       {};