Introduce TaskRunnerHandle.

base/threading/task_runner_handle.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 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"
+
+namespace base {
+
+class SequencedTaskRunner;
+class SingleThreadTaskRunner;
+class TaskRunner;
+
+class BASE_EXPORT TaskRunnerHandle {
+ public:
+  // Returns a TaskRunner which will run tasks in the same context as the
+  // current task. That context could, for example, 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. 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
+  // HasSingleThreadedTaskScope(). Only use this when thread-affinity is
+  // required, prefer Get() or GetSequenced() otherwise.
+  static scoped_refptr<SingleThreadTaskRunner> GetSingleThreaded();
+
+  // Returns true if the current task is running as part of any TaskScope.
+  static bool HasTaskScope();

[fdoray, 2016/06/08 18:10:44]

HasTaskContext? or just HasContext? since the comment above Get() says that it
returns a TaskRunner which will run tasks in the "same context"

HasSequencedTaskContext? or HasSequencedContext?
HasSingleThreadTaskContext? or HasSingleThreadContext?

[gab, 2016/06/08 20:29:19]

I agree that sounds a bit better but it clashes with *TaskScope, perhaps the
scopes should be named *TaskContext?

+
+  // 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.
+  static bool HasSequencedTaskScope();

[fdoray, 2016/06/08 18:10:44]

HasSequencedContext?

[gab, 2016/06/08 20:29:19]

Acknowledged.

+
+  // Returns true if the current task is running as part of a
+  // SingleThreadTaskScope.
+  static bool HasSingleThreadTaskScope();
+
+  // Each task in Chromium should run in one and only one Scope. The

[fdoray, 2016/06/08 18:10:44]

Remove Chromium?

[gab, 2016/06/08 20:29:19]

Done.

+  // 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, holds 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);
+    ~TaskScope();
+
+   private:
+    friend class TaskRunnerHandle;
+
+    // Immutable TaskRunner state.
+    const scoped_refptr<TaskRunner> task_runner_;
+
+    DISALLOW_COPY_AND_ASSIGN(TaskScope);
+  };
+
+  // A SequencedTaskScope which, throughout its lifetime, holds 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);
+    ~SequencedTaskScope();
+
+   private:
+    friend class TaskRunnerHandle;
+
+    // Immutable SequencedTaskRunner state.
+    const scoped_refptr<SequencedTaskRunner> sequenced_task_runner_;
+
+    DISALLOW_COPY_AND_ASSIGN(SequencedTaskScope);
+  };
+
+  // A SingleThreadedTaskScope which, throughout its lifetime, holds the single-
+  // threaded context (SingleThreadedTaskRunner) in which tasks on the thread it
+  // lives on run in.
+  class BASE_EXPORT SingleThreadTaskScope {
+   public:
+    SingleThreadTaskScope(
+        scoped_refptr<SingleThreadTaskRunner> single_thread_task_runner);
+    ~SingleThreadTaskScope();
+
+   private:
+    friend class TaskRunnerHandle;
+
+    // Immutable SingleThreadTaskRunner state.
+    const scoped_refptr<SingleThreadTaskRunner> single_thread_task_runner_;
+
+    DISALLOW_COPY_AND_ASSIGN(SingleThreadTaskScope);
+  };
+
+ private:
+  DISALLOW_IMPLICIT_CONSTRUCTORS(TaskRunnerHandle);
+};
+
+}  // namespace base
+
+#endif  // BASE_THREADING_TASK_RUNNER_HANDLE_H_