Introduce TaskRunnerHandle.

base/threading/task_runner_handle.h

Index: base/threading/task_runner_handle.h
diff --git a/base/threading/task_runner_handle.h b/base/threading/task_runner_handle.h
new file mode 100644
index 0000000000000000000000000000000000000000..42dace75072a8b428adfc1680e18fb851346f3c2
--- /dev/null
+++ b/base/threading/task_runner_handle.h
@@ -0,0 +1,107 @@
+// 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 BASE_THREADING_TASK_RUNNER_HANDLE_H_
+#define BASE_THREADING_TASK_RUNNER_HANDLE_H_
+
+#include "base/base_export.h"
+#include "base/macros.h"
+#include "base/memory/ref_counted.h"
+#include "base/sequenced_task_runner.h"
+#include "base/single_thread_task_runner.h"
+#include "base/task_runner.h"
+#include "base/threading/task_runner_handle_internal.h"
+
+namespace base {
+
+class BASE_EXPORT TaskRunnerHandle {
+ public:
+  // Returns a TaskRunner which will run tasks in the same context as the
+  // current task. That context could be: a MessageLoop, a sequence on a thread
+  // pool, or merely the current set of TaskTraits on a non-sequenced
+  // TaskScheduler task.
+  static scoped_refptr<TaskRunner> Get();
+
+  // Returns a SequencedTaskRunner associated with the current sequence. This
+  // must only be called if HasSequencedTaskScope(). Prefer Get() to this when
+  // sequencing is not required.

[fdoray, 2016/06/17 14:29:02]

s/This must only be called.../This DCHECKs if !HasSequencedTaskScope()./

We don't expect users to call HasSequencedTaskScope() if they know that they are
on a sequence. They shouldn't do this:

DCHECK(TaskRunnerHandle::HasSequencedTaskScope());
TaskRunnerHandle::GetSequenced()->...

[gab, 2016/06/20 19:55:36]

Done.

+  // TODO(gab): Migrate all callsites using SequencedTaskRunnerHandle::Get() to
+  // TaskRunnerHandle::Get() and remove support for getting a
+  // SequencedTaskRunner from a non-sequenced task in SequencedWorkerPool which
+  // currently breaks the semantics intended here.
+  static scoped_refptr<SequencedTaskRunner> GetSequenced();
+
+  // Returns a SingleThreadTaskRunner associated with the current
+  // single-threaded sequence. This must only be called if

[fdoray, 2016/06/17 14:29:02]

s/This must only be called.../This DCHECKS if !HasSingleThreadedTaskScope()/

[gab, 2016/06/20 19:55:36]

Done.

+  // HasSingleThreadedTaskScope(). Only use this when thread-affinity is
+  // required, prefer Get() or GetSequenced() otherwise.
+  static scoped_refptr<SingleThreadTaskRunner> GetSingleThreaded();

[fdoray, 2016/06/17 14:29:02]

Why do we have GetSingleThread*ed*() and HasSingleThread*TaskScope()?

[gab, 2016/06/20 19:55:36]

Because we have SingleThread*TaskRunner already but GetSingleThread() sounds
silly IMO. Because of the legacy SingleThreadTaskRunner naming I decided to use
SingleThreadTaskScope as its related name and things derived from it except for
GetSingleThread()... Happy to field other suggestions.

+
+  // Returns true if the current task is running as part of any TaskScope.
+  static bool HasTaskScope();
+
+  // Returns true if the current task is running as part of a SequencedTaskScope
+  // or a SingleThreadTaskScope. Note: This currently also supports
+  // SequencedWorkerPool's threads although they don't explicitly have a
+  // SequencedTaskScope but this support will be going away with the migration
+  // to the TaskScheduler.

[fdoray, 2016/06/17 14:29:02]

TODO(gab): Remove this comment after SequencedWorkerPool has been migrated to
the TaskScheduler.

[gab, 2016/06/20 19:55:36]

Reworded to include TODO

+  static bool HasSequencedTaskScope();
+
+  // Returns true if the current task is running as part of a
+  // SingleThreadTaskScope.
+  static bool HasSingleThreadTaskScope();
+
+  // Each task should run in one and only one TaskScope (TaskScopes are held on
+  // the stack in the scope of a task and no TaskScope can live inside another
+  // TaskScope). The more specific Scopes enable the more generic getters but
+  // not vice-versa (e.g. SequencedTaskScope enables Get() and GetSequenced()
+  // but not GetSingleThreaded()).
+
+  // A TaskScope which, throughout its lifetime, identifies the context
+  // (TaskRunner) in which tasks on the thread it lives on run in.
+  class BASE_EXPORT TaskScope {
+   public:
+    TaskScope(scoped_refptr<TaskRunner> task_runner);

[fdoray, 2016/06/17 14:29:02]

The destructor is not trivial. ~TaskScope() here and TaskScope::~TaskScope() =
default; in the .cc file?

https://www.chromium.org/developers/coding-style/cpp-dos-and-donts#TOC-When-y...

[gab, 2016/06/20 19:55:36]

It isn't but it only deletes TaskScopeState which itself has an explicit
out-of-line destructor. So IMO it's okay to have TaskScope's destructor
inline...

+
+   private:
+    const internal::TaskScopeState state_;
+
+    DISALLOW_COPY_AND_ASSIGN(TaskScope);
+  };
+
+  // A SequencedTaskScope which, throughout its lifetime, identifies the
+  // sequenced context (SequencedTaskRunner) in which tasks on the thread it
+  // lives on run in.
+  class BASE_EXPORT SequencedTaskScope {
+   public:
+    SequencedTaskScope(
+        scoped_refptr<SequencedTaskRunner> sequenced_task_runner);
+
+   private:
+    const internal::TaskScopeState state_;
+
+    DISALLOW_COPY_AND_ASSIGN(SequencedTaskScope);
+  };
+
+  // A SingleThreadedTaskScope which, throughout its lifetime, identifies the
+  // single- threaded context (SingleThreadedTaskRunner) in which tasks on the

[fdoray, 2016/06/17 14:29:02]

SingleThread**TaskRunner :)

[fdoray, 2016/06/17 14:29:02]

single- threaded
remove extra space

[gab, 2016/06/20 19:55:36]

Done.

[gab, 2016/06/20 19:55:36]

Done (I hate that name!)

+  // thread it lives on run in.
+  class BASE_EXPORT SingleThreadTaskScope {
+   public:
+    SingleThreadTaskScope(
+        scoped_refptr<SingleThreadTaskRunner> single_thread_task_runner);
+
+   private:
+    const internal::TaskScopeState state_;
+
+    DISALLOW_COPY_AND_ASSIGN(SingleThreadTaskScope);
+  };
+
+ private:
+  DISALLOW_IMPLICIT_CONSTRUCTORS(TaskRunnerHandle);
+};
+
+}  // namespace base
+
+#endif  // BASE_THREADING_TASK_RUNNER_HANDLE_H_