Add TaskTraits::MayBlock and TaskTraits::WithSyncPrimitives.

base/task_scheduler/task_traits.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_TASK_SCHEDULER_TASK_TRAITS_H_
 #define BASE_TASK_SCHEDULER_TASK_TRAITS_H_
 
 #include <stdint.h>
 
 #include <iosfwd>
@@ skipping 60 matching lines @@
   // critical user data.
   //
   // Note: Tasks with BACKGROUND priority that block shutdown will be promoted
   // to USER_VISIBLE priority during shutdown.
   BLOCK_SHUTDOWN,
 };
 
 // Describes metadata for a single task or a group of tasks.
 class BASE_EXPORT TaskTraits {
  public:
-  // Constructs a default TaskTraits for tasks with
-  //     (1) no I/O,
-  //     (2) priority inherited from the calling context, and
+  // Constructs a default TaskTraits for tasks that
+  //     (1) do not make blocking calls
+  //     (2) can inherit their priority from the calling context, and
   //     (3) may block shutdown or be skipped on shutdown.
   // Tasks that require stricter guarantees and/or know the specific
   // TaskPriority appropriate for them should highlight those by requesting
   // explicit traits below.
   TaskTraits();
   TaskTraits(const TaskTraits& other) = default;
   TaskTraits& operator=(const TaskTraits& other) = default;
   ~TaskTraits();
 
-  // Allows tasks with these traits to wait on synchronous file I/O.
+  // Tasks with this trait may block. This includes but is not limited to tasks
+  // that wait on synchronous file I/O operations: read or write a file from
+  // disk, a pipe or a socket, rename or delete a file, enumerate files in a

[gab, 2016/12/20 17:13:54]

interact with a pipe or a socket
^^^^^^^^

(i.e. every enumeration begins with a verb and this one should too)

[fdoray, 2016/12/20 20:58:06]

Done.

+  // directory, etc. Do not use this trait just to use locks. For tasks that

[gab, 2016/12/20 17:13:53]

s/Do not use this trait just to use locks./This trait isn't required for the
mere use of locks./ ?

[robliao, 2016/12/20 18:27:50]

I strengthened the wording to make it clear that if you're just using locks,
don't use this trait. If we're concerned about skimmers, we also need to be very
strong in our language.

[fdoray, 2016/12/20 20:58:06]

Done.

+  // join threads or processes or wait on a waitable event or condition

[gab, 2016/12/20 17:13:54]

threads/processes or wait on a WaitableEvent/ConditionVariable

(to try to reduce "or"s ?)

[robliao, 2016/12/20 18:27:50]

Could be 

For tasks that block on synchronization primitives (thread handles, waitable
events, condition variables), see WithSyncPrimitives().

Or

For tasks that interact with synchronization primitives like joining against a
thread, waiting on WaitableEvent, or waiting on a ConditionVariable, see
WithSyncPrimitives().

[fdoray, 2016/12/20 20:58:06]

Done.

+  // variable, see WithSyncPrimitives().
+  TaskTraits& MayBlock();
+
+  // Tasks with this trait are allowed to wait on waitable events and condition
+  // variables as well as to join threads and processes. This trait implies
+  // MayBlock().
+  //
+  // This trait should generally not be used.
+  //
+  // Instead of waiting on a waitable event or a condition variable, put the
+  // work that should happen after the wait in a callback and post that callback
+  // from where the waitable event or condition variable would have been
+  // signaled. If something needs to be scheduled after many tasks have
+  // executed, use base::BarrierClosure.
+  //
+  // On Windows, join processes asynchronously using base::win::ObjectWatcher.
+  //
+  // Avoid creating threads. Instead, use
+  // base::Create(Sequenced|SingleTreaded)TaskRunnerWithTraits(). If a thread is
+  // really needed, make it non-joinable and add cleanup work at the end of the
+  // thread's main function (if using base::Thread, override Cleanup()).
+  TaskTraits& WithSyncPrimitives();
+
+  // DEPRECATED
+  // TODO(fdoray): Remove this as part of crbug.com/675660
   TaskTraits& WithFileIO();
 
-  // Allows tasks with these traits to wait on things other than file I/O. In
-  // particular, they may wait on a WaitableEvent or a ConditionVariable, join a
-  // thread or a process, or make a blocking system call that doesn't involve
-  // interactions with the file system.
+  // DEPRECATED
+  // TODO(fdoray): Remove this as part of crbug.com/675660
   TaskTraits& WithWait();
 
   // Applies |priority| to tasks with these traits.
   TaskTraits& WithPriority(TaskPriority priority);
 
   // Applies |shutdown_behavior| to tasks with these traits.
   TaskTraits& WithShutdownBehavior(TaskShutdownBehavior shutdown_behavior);
 
-  // Returns true if waiting on synchronous file I/O is allowed by these traits.
-  bool with_file_io() const { return with_file_io_; }
+  // Returns true if tasks with these traits may block.
+  bool may_block() const { return may_block_; }
 
-  // Returns true if waiting on things other than file I/O is allowed by these
-  // traits.
-  bool with_wait() const { return with_wait_; }
+  // Returns true if tasks with these traits may wait on sync primitives.
+  bool with_sync_primitives() const { return with_sync_primitives_; }
+
+  // DEPRECATED
+  // TODO(fdoray): Remove this as part of crbug.com/675660
+  bool with_file_io() const { return may_block(); }
 
   // 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_;
-  bool with_wait_;
+  bool may_block_;
+  bool with_sync_primitives_;
   TaskPriority priority_;
   TaskShutdownBehavior shutdown_behavior_;
 };
 
 // Returns string literals for the enums defined in this file. These methods
 // should only be used for tracing and debugging.
 BASE_EXPORT const char* TaskPriorityToString(TaskPriority task_priority);
 BASE_EXPORT const char* TaskShutdownBehaviorToString(
     TaskShutdownBehavior task_priority);
 
 // Stream operators so that the enums defined in this file can be used in
 // DCHECK and EXPECT statements.
 BASE_EXPORT std::ostream& operator<<(std::ostream& os,
                                      const TaskPriority& shutdown_behavior);
 BASE_EXPORT std::ostream& operator<<(
     std::ostream& os,
     const TaskShutdownBehavior& shutdown_behavior);
 
 }  // namespace base
 
 #endif  // BASE_TASK_SCHEDULER_TASK_TRAITS_H_