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"
+#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
+  // DCHECKs 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 DCHECKs 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();
+
+  // Returns true if the current task is running as part of a SequencedTaskScope
+  // or a SingleThreadTaskScope. TODO(gab): This currently also supports
+  // SequencedWorkerPool's threads although they don't explicitly have a
+  // SequencedTaskScope but this support will be removed with the migration to
+  // the TaskScheduler.
+  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 a default context
+  // (thread/sequence/etc.) that tasks can be posted to on the thread it lives
+  // on.
+  class BASE_EXPORT TaskScope {
+   public:
+    TaskScope(scoped_refptr<TaskRunner> task_runner);
+
+   private:
+    const internal::TaskScopeState state_;
+
+    DISALLOW_COPY_AND_ASSIGN(TaskScope);
+  };
+
+  // A SequencedTaskScope which, throughout its lifetime, identifies a default
+  // sequenced context that tasks can be posted to on the thread it lives on.
+  class BASE_EXPORT SequencedTaskScope {
+   public:
+    SequencedTaskScope(
+        scoped_refptr<SequencedTaskRunner> sequenced_task_runner);
+
+   private:
+    const internal::TaskScopeState state_;
+
+    DISALLOW_COPY_AND_ASSIGN(SequencedTaskScope);
+  };
+
+  // A SequencedTaskScope which, throughout its lifetime, identifies a default
+  // single-threaded context that tasks can be posted to on the thread it lives
+  // on.
+  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_