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
+  // directory, etc. It is not necessary to use this trait to use locks. For
+  // tasks that join threads or processes or wait on a waitable event or
+  // condition variable, see WithSyncPrimitives().
+  TaskTraits& MayBlock();
+
+  // Tasks with this trait are allowed to wait on waitable events and condition
+  // variables and to join threads and processes. This trait implies MayBlock().

[gab, 2016/12/19 20:20:14]

s/and to/as well as/

[fdoray, 2016/12/19 21:22:43]

Done.

+  //
+  // In general, you should not use this trait.

[gab, 2016/12/19 20:20:14]

// This trait should generally not be used.

 (to avoid "you")

[fdoray, 2016/12/19 21:22:43]

Done.

+  //

[gab, 2016/12/19 20:20:14]

Check with jam@ whether we should make this trait require friend'ing (to have
OWNERS control over usage like for thread_restrictions.h). Otherwise we leak a
way to make a task be allowed to wait without it requiring a new friend decl.

[fdoray, 2016/12/19 21:22:43]

jam@: wdyt?

Note that today, you only need to be a friend of ThreadRestrictions to wait from
a thread that explicitly disallows waiting. Tasks with .WithSyncPrimitives() a
scheduled in a pool dedicated to blocking tasks, so we're not really leaking a
way to wait from somewhere you're not supposed to.

[jam, 2016/12/19 23:17:34]

If it's only used on non UI/IO threads that are meant to have blocking tasks, no
friending needed. The thread_Restrictions friend this was done specifically to
not allow blocking the UI/IO threads.

Thanks for checking

+  // Instead of waiting on a waitable event or a condition variable, put the
+  // work that you would have done after the wait in a callback and post this

[gab, 2016/12/19 20:20:14]

s/this callback/that callback/

[gab, 2016/12/19 20:20:14]

s/that you would have done/that should happen/

[fdoray, 2016/12/19 21:22:43]

Done.

[fdoray, 2016/12/19 21:22:43]

Done.

+  // callback from where you would have signaled the waitable event or condition

[gab, 2016/12/19 20:20:14]

s/you would have signaled the WE or CV/from where the WE or CV would have been
signaled/

[fdoray, 2016/12/19 21:22:43]

Done.

+  // variable. If you need to do something after a bunch of tasks have run, use
+  // base::BarrierClosure.

[gab, 2016/12/19 20:20:14]

// If something needs to be scheduled after many tasks have executed, use ...

[fdoray, 2016/12/19 21:22:43]

Done.

+  //
+  // On Windows, join processes asynchronously using base::win::ObjectWatcher.
+  //
+  // Avoid creating threads. Instead, use
+  // base::Create(Sequenced|SingleTreaded)TaskRunnerWithTraits(). If you really
+  // need a thread, make it non-joinable and add cleanup work at the end of the

[gab, 2016/12/19 20:20:14]

If a thread is really needed,

[fdoray, 2016/12/19 21:22:43]

Done.

+  // thread's main function (if you use base::Thread, override Cleanup()).

[gab, 2016/12/19 20:20:14]

if using base::Thread, ...

[fdoray, 2016/12/19 21:22:43]

Done.

+  TaskTraits& WithSyncPrimitives();
+
+  // DEPRECATED
+  // TODO(fdoray): Remove this crbug.com/675660

[gab, 2016/12/19 20:20:14]

Removes this as part of crbug...
             ^^^^^^^^^^

[fdoray, 2016/12/19 21:22:43]

Done.

   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 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 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_