Chrome Task Scheduler Task Traits

base/task_scheduler/task_traits.h

Index: base/task_scheduler/task_traits.h
diff --git a/base/task_scheduler/task_traits.h b/base/task_scheduler/task_traits.h
new file mode 100644
index 0000000000000000000000000000000000000000..8fb864073e9ad528695adef1bb7852e2a23c1b3e
--- /dev/null
+++ b/base/task_scheduler/task_traits.h
@@ -0,0 +1,137 @@
+// 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_TASK_SCHEDULER_TASK_TRAITS_H_
+#define BASE_TASK_SCHEDULER_TASK_TRAITS_H_
+
+#include "base/base_export.h"
+#include "build/build_config.h"
+
+namespace base {
+
+using TaskPriorityUnderlyingType = char;
+
+enum class TaskPriority : TaskPriorityUnderlyingType {
+  // This task affects UI immediately after a user interaction.
+  // Example: Generating data shown in the UI immediately after a click.
+  USER_BLOCKING = 2,
+  // This task affects UI or responsiveness of future user interactions. It is
+  // not an immediate response to a user interaction.
+  // Examples:
+  // - Updating the UI to reflect that a long task was completed.

[gab, 2016/02/16 22:15:43]

"to reflect progress on a long task." (i.e. generically talking about download
progress) ?

(i.e. otherwise I find this clashes with BACKGROUND as there we say : "user
won't notice if it takes a long time" but then we say that the UI update to a
long task is USER_VISIBLE)

[robliao, 2016/02/16 22:58:31]

sg. Done.

+  // - Loading data that might be shown in the UI after a future user
+  //   interaction.
+  USER_VISIBLE = 1,
+  // Everything else (user won't notice if this takes an arbitrarily long time
+  // to complete).
+  BACKGROUND = 0,
+};
+
+const TaskPriorityUnderlyingType kNumTaskPriorities = 3;
+
+enum class TaskShutdownBehavior {
+  // Tasks posted with this mode which have not started executing before
+  // shutdown is initiated will never run. Tasks with this mode running at
+  // shutdown will be ignored (the worker thread will not be joined).
+  //
+  // This option provides a nice way to post stuff you don't want blocking
+  // shutdown. For example, you might be doing a slow DNS lookup and if it's
+  // blocked on the OS, you may not want to stop shutdown, since the result
+  // doesn't really matter at that point.
+  //
+  // However, you need to be very careful what you do in your callback when you
+  // use this option. Since the thread will continue to run until the OS
+  // terminates the process, the app can be in the process of tearing down when
+  // you're running. This means any singletons or global objects you use may
+  // suddenly become invalid out from under you. For this reason, it's best to
+  // use this only for slow but simple operations like the DNS example.
+  CONTINUE_ON_SHUTDOWN,
+
+  // Tasks posted with this mode that have not started executing at
+  // shutdown will never run. However, any task that has already begun
+  // executing when shutdown is invoked will be allowed to continue and
+  // will block shutdown until completion.
+  //
+  // Note: Because TaskScheduler::Shutdown() may block while these tasks are
+  // executing, care must be taken to ensure that they do not block on the
+  // thread that called TaskScheduler::Shutdown(), as this may lead to deadlock.
+  SKIP_ON_SHUTDOWN,
+
+  // Tasks posted with this mode before shutdown is complete will block shutdown
+  // until they're executed. Generally, this should be used only to save
+  // critical user data.
+  //
+  // Note: Tasks with BACKGROUND priority that block shutdown will be promoted
+  // to USER_VISIBLE priority during shutdown.
+  BLOCK_SHUTDOWN,
+};
+
+// TaskTraits holds metadata about a task and prevents the combinatorial
+// explosion of PostTaskWith*() call sites.

[gab, 2016/02/16 22:15:43]

I guess the comment about preventing combinatorial explosion was nice for the
doc to justify using this over crrent PostTaskWith*() paradigm but in the
codebase it feels out of place, something like this is sufficient IMO:

// TaskTraits holds metadata to be associated to a task or group of tasks.

[robliao, 2016/02/16 22:58:31]

Updated. Done.

+// Usage example:
+//     PostTaskWithTraits(
+//         FROM_HERE, TaskTraits().WithFileIO().WithPriority(USER_VISIBLE),
+//         Bind(...));
+struct BASE_EXPORT TaskTraits {
+  // Constructs a default TaskTraits for tasks with
+  //     (1) no I/O,
+  //     (2) low priority, and
+  //     (3) may block shutdown or be skipped on shutdown.
+  // Tasks that require stricter guarantees should highlight those by requesting
+  // explicit traits below.
+  TaskTraits();
+  ~TaskTraits();
+
+  // Allows tasks with these traits to do file I/O.
+  TaskTraits& WithFileIO();
+
+  // Applies a priority to tasks with these traits.

[gab, 2016/02/16 22:15:43]

s/a priority/|priority|/

[robliao, 2016/02/16 22:58:31]

Done.

+  TaskTraits& WithPriority(TaskPriority priority);
+
+  // Applies a shutdown behavior to tasks with these traits.

[gab, 2016/02/16 22:15:43]

s/a shutdown behavior/|shutdown_behavior|/

[robliao, 2016/02/16 22:58:31]

Done.

+  TaskTraits& WithShutdownBehavior(TaskShutdownBehavior behavior);
+
+  // Returns true if file I/O is allowed by these traits.
+  bool with_file_io() const { return with_file_io_; }
+
+  // Returns the priority of tasks with these traits.
+  TaskPriority priority() const { return priority_; }
+
+  // Returns the shutdown behavior of tasks with these traits.
+  TaskShutdownBehavior shutdown_behavior() const { return shutdown_behavior_; }
+
+ private:
+  bool with_file_io_;
+  TaskPriority priority_;
+  TaskShutdownBehavior shutdown_behavior_;
+};
+
+// The ExecutionMode of a task runner determines whether the tasks posted to
+// it are executed in parallel, in sequence or on a single thread.
+enum class ExecutionMode {
+  // Can execute multiple tasks at a time. High priority tasks will execute
+  // first under contention.

[fdoray, 2016/02/16 21:47:00]

Maybe just "Can execute multiple tasks at a time."

All tasks posted to a given PARALLEL TaskRunner have the same priority, so "High
priority tasks will execute first under contention." doesn't really make sense.

[robliao, 2016/02/16 21:55:04]

CreateChildTaskRunnerWithTraits makes it so that these rules are important since
they allow the different priorities to enter the picture. It doesn't change the
fact that these describe the general behavior of the task runner. It should do
okay here, especially if we introduce other ways to change priorities of tasks
in the future.

[gab, 2016/02/16 22:15:43]

Agreed and executing first compared to others is inherited from the definition
of TaskPriority.

[robliao, 2016/02/16 22:58:31]

Discussed offline.

+  PARALLEL,
+
+  // Executes one task at a time. Tasks are guaranteed to run in posting order.
+  // The sequence’s priority will be that of its pending task with the highest
+  // priority.

[fdoray, 2016/02/16 21:47:00]

Maybe just "Executes one task at a time. Tasks are guaranteed to run in posting
order."

The last sentence is only relevant for CreateChildTaskRunner, so maybe we put it
next to the declaration of that function?

[robliao, 2016/02/16 21:55:04]

See previous comment.

[gab, 2016/02/16 22:15:43]

+1

[robliao, 2016/02/16 22:58:31]

Discussed offline.

+  SEQUENCED,
+
+  // Executes one task at a time on a single thread. Tasks are guaranteed to run
+  // in posting order.
+  SINGLE_THREADED,
+
+#if defined(OS_WIN)
+  // Executes one task at a time on a single thread that has initialized the COM
+  // library with the single-threaded apartment (STA) concurrency model. Tasks
+  // are guaranteed to run in posting order and the assigned thread will also
+  // process COM messages so long as the associated TaskRunner is kept alive.
+  SINGLE_THREADED_COM_STA,

[gab, 2016/02/16 22:15:43]

Maybe keep this back for the CL that will implement COM all at once?

[robliao, 2016/02/16 22:58:31]

Makes sense to me. Done.

+#endif  // defined(OS_WIN)
+};
+
+}  // namespace base
+
+#endif  // BASE_TASK_SCHEDULER_TASK_TRAITS_H_