[Offline pages] Introduces TaskQueue to serialize tasks that asynchronously access SQLStore

components/offline_pages/core/task.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef COMPONENTS_OFFLINE_PAGES_CORE_TASK_H_
+#define COMPONENTS_OFFLINE_PAGES_CORE_TASK_H_
+
+#include "base/callback.h"
+#include "base/macros.h"
+#include "base/memory/ref_counted.h"
+#include "base/single_thread_task_runner.h"
+
+namespace offline_pages {
+
+// Task interface for consumers of the TaskQueue. Implements a mechanism for
+// task completion.
+//
+// To create your own Task:
+// * Derive your new task from offline_pages::Task.
+// * Implement your task with as many async operations on the controlled
+//   resource as is required. (In general the smaller the task the better.)
+// * Whenever the task is terminated, call |Complete|.
+// * To schedule task for execution call |TaskQueue::AddTask|.
+//
+// If there is a chance that a task callback will come after the task is
+// destroyed, it is up to the task to actually implement mechanism to deal with
+// that, such as using a |base::WeakPtrFactory|.
+class Task {
+ public:
+  // Signature of the method to be called by a task, when its work is done.
+  typedef base::Callback<void(Task*)> TaskCompletionCallback;
+
+  Task();
+  virtual ~Task();
+
+  // Entry point to the task. This is used by the queue to start the task, and
+  // first step of the task should be implemented by overloading this method.
+  // The task should define an additional method for every asynchronous step,
+  // with each step setting up the next step as a callback.
+  // TODO(fgorski): Consider alternative: protected RunImpl(), so that we can
+  // add things like UMA in the Run method.
+  virtual void Run() = 0;
+
+  // Sets the |task_completion_callback| and single thread task
+  // |task_completion_runner| that will be used to inform the task owner that
+  // the task is done.
+  //
+  // In production the task owner should be a |TaskQueue|.
+  //
+  // Should only be called once, by |TaskQueue|. Should not be called from
+  // within the |Task|.
+  //
+  // If the task is run outside of the |TaskQueue| and completion callback is
+  // not set, it will also work.
+  //
+  // When defining a new task, this is not the callback to be used to inform the
+  // caller of task completion, it is only used between the |TaskQueue| and the
+  // |Task| to make sure it can be properly cleaned up.
+  //
+  // Left public for testing.
+  void SetTaskCompletionCallback(
+      scoped_refptr<base::SingleThreadTaskRunner> task_completion_runner,
+      const TaskCompletionCallback& task_completion_callback);
+
+ protected:
+  // Call |TaskComplete| as the last call, before the task is terminated. This
+  // ensures that |TaskQueue| can pick up another task.
+  // |task_completion_callback_| will be scheduled on the provided
+  // |task_completion_runner_|, which means task code is no longer going to be
+  // on stack, when the next call is made.
+  void TaskComplete();

[dewittj, 2016/09/29 18:40:55]

Feels like TaskQueue should be a TaskDelegate with a Complete() function that
can do the completion callback and know about the runner.  Then this task API
would be even simpler.  You could have a SetDelegate API that TaskQueue calls,
or take a TaskDelegate in the constructor.

[fgorski, 2016/09/30 17:33:12]

As we discussed, it may be harder to work with if we introduce the delegate and
I don't want the Task to know about the Queue directly.
I do however want the queue to have a final say about the completion callback
when accepting the task. 

Leaving it as is for now.

+
+ private:
+  // Completion callback for this task set by |SetTaskCompletionCallback|.
+  TaskCompletionCallback task_completion_callback_;
+  // Task runner for calling completion callback. Set by
+  // |SetTaskCompletionCallback|.
+  scoped_refptr<base::SingleThreadTaskRunner> task_completion_runner_;
+
+  DISALLOW_COPY_AND_ASSIGN(Task);
+};
+
+}  // namespace offline_pages
+
+#endif  // COMPONENTS_OFFLINE_PAGES_CORE_TASK_H_