OLD | NEW |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | 1 // Copyright 2016 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef BASE_TASK_SCHEDULER_TASK_TRAITS_H_ | 5 #ifndef BASE_TASK_SCHEDULER_TASK_TRAITS_H_ |
6 #define BASE_TASK_SCHEDULER_TASK_TRAITS_H_ | 6 #define BASE_TASK_SCHEDULER_TASK_TRAITS_H_ |
7 | 7 |
8 #include <stdint.h> | 8 #include <stdint.h> |
9 | 9 |
10 #include <iosfwd> | 10 #include <iosfwd> |
| 11 #include <type_traits> |
11 | 12 |
12 #include "base/base_export.h" | 13 #include "base/base_export.h" |
| 14 #include "base/task_scheduler/task_traits_details.h" |
13 #include "build/build_config.h" | 15 #include "build/build_config.h" |
14 | 16 |
15 namespace base { | 17 namespace base { |
16 | 18 |
17 // Valid priorities supported by the task scheduler. Note: internal algorithms | 19 // Valid priorities supported by the task scheduler. Note: internal algorithms |
18 // depend on priorities being expressed as a continuous zero-based list from | 20 // depend on priorities being expressed as a continuous zero-based list from |
19 // lowest to highest priority. Users of this API shouldn't otherwise care about | 21 // lowest to highest priority. Users of this API shouldn't otherwise care about |
20 // nor use the underlying values. | 22 // nor use the underlying values. |
21 enum class TaskPriority { | 23 enum class TaskPriority { |
22 // This will always be equal to the lowest priority available. | 24 // This will always be equal to the lowest priority available. |
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
68 | 70 |
69 // Tasks posted with this mode before shutdown is complete will block shutdown | 71 // Tasks posted with this mode before shutdown is complete will block shutdown |
70 // until they're executed. Generally, this should be used only to save | 72 // until they're executed. Generally, this should be used only to save |
71 // critical user data. | 73 // critical user data. |
72 // | 74 // |
73 // Note: Tasks with BACKGROUND priority that block shutdown will be promoted | 75 // Note: Tasks with BACKGROUND priority that block shutdown will be promoted |
74 // to USER_VISIBLE priority during shutdown. | 76 // to USER_VISIBLE priority during shutdown. |
75 BLOCK_SHUTDOWN, | 77 BLOCK_SHUTDOWN, |
76 }; | 78 }; |
77 | 79 |
| 80 // Tasks with this trait may block. This includes but is not limited to tasks |
| 81 // that wait on synchronous file I/O operations: read or write a file from disk, |
| 82 // interact with a pipe or a socket, rename or delete a file, enumerate files in |
| 83 // a directory, etc. This trait isn't required for the mere use of locks. For |
| 84 // tasks that block on base/ synchronization primitives, see the |
| 85 // WithBaseSyncPrimitives trait. |
| 86 struct MayBlock {}; |
| 87 |
| 88 // Tasks with this trait will pass base::AssertWaitAllowed(), i.e. will be |
| 89 // allowed on the following methods : |
| 90 // - base::WaitableEvent::Wait |
| 91 // - base::ConditionVariable::Wait |
| 92 // - base::PlatformThread::Join |
| 93 // - base::PlatformThread::Sleep |
| 94 // - base::Process::WaitForExit |
| 95 // - base::Process::WaitForExitWithTimeout |
| 96 // |
| 97 // Tasks should generally not use these methods. |
| 98 // |
| 99 // Instead of waiting on a WaitableEvent or a ConditionVariable, put the work |
| 100 // that should happen after the wait in a callback and post that callback from |
| 101 // where the WaitableEvent or ConditionVariable would have been signaled. If |
| 102 // something needs to be scheduled after many tasks have executed, use |
| 103 // base::BarrierClosure. |
| 104 // |
| 105 // On Windows, join processes asynchronously using base::win::ObjectWatcher. |
| 106 // |
| 107 // MayBlock() must be specified in conjunction with this trait if and only if |
| 108 // removing usage of methods listed above in the labeled tasks would still |
| 109 // result in tasks that may block (per MayBlock()'s definition). |
| 110 // |
| 111 // In doubt, consult with //base/task_scheduler/OWNERS. |
| 112 struct WithBaseSyncPrimitives {}; |
| 113 |
78 // Describes metadata for a single task or a group of tasks. | 114 // Describes metadata for a single task or a group of tasks. |
79 class BASE_EXPORT TaskTraits { | 115 class BASE_EXPORT TaskTraits { |
| 116 private: |
| 117 // ValidTrait ensures TaskTraits' constructor only accepts appropriate types. |
| 118 // |
| 119 // TODO(fdoray): Remove base:: prefixes once the TaskTraits::MayBlock() and |
| 120 // TaskTraits::WithBaseSyncPrimitives() methods are gone. |
| 121 // https://crbug.com/713683 |
| 122 struct ValidTrait { |
| 123 ValidTrait(TaskPriority) {} |
| 124 ValidTrait(TaskShutdownBehavior) {} |
| 125 ValidTrait(base::MayBlock) {} |
| 126 ValidTrait(base::WithBaseSyncPrimitives) {} |
| 127 }; |
| 128 |
80 public: | 129 public: |
81 // Constructs a default TaskTraits for tasks that | 130 // Invoking this constructor without arguments produces TaskTraits that are |
| 131 // appropriate for tasks that |
82 // (1) don't block (ref. MayBlock() and WithBaseSyncPrimitives()), | 132 // (1) don't block (ref. MayBlock() and WithBaseSyncPrimitives()), |
83 // (2) prefer inheriting the current priority to specifying their own, and | 133 // (2) prefer inheriting the current priority to specifying their own, and |
84 // (3) can either block shutdown or be skipped on shutdown | 134 // (3) can either block shutdown or be skipped on shutdown |
85 // (TaskScheduler implementation is free to choose a fitting default). | 135 // (TaskScheduler implementation is free to choose a fitting default). |
86 // Tasks that require stricter guarantees and/or know the specific | 136 // |
87 // TaskPriority appropriate for them should highlight those by requesting | 137 // To get TaskTraits for tasks that require stricter guarantees and/or know |
88 // explicit traits below. | 138 // the specific TaskPriority appropriate for them, provide arguments of type |
89 TaskTraits(); | 139 // TaskPriority, TaskShutdownBehavior, MayBlock, and/or WithBaseSyncPrimitives |
90 TaskTraits(const TaskTraits& other) = default; | 140 // in any order to the constructor. |
| 141 // |
| 142 // E.g. |
| 143 // constexpr base::TaskTraits default_traits = {}; |
| 144 // constexpr base::TaskTraits user_visible_traits = |
| 145 // {base::TaskPriority::USER_VISIBLE}; |
| 146 // constexpr base::TaskTraits user_visible_may_block_traits = { |
| 147 // base::TaskPriority::USER_VISIBLE, base::MayBlock()}; |
| 148 // constexpr base::TaskTraits other_user_visible_may_block_traits = { |
| 149 // base::MayBlock(), base::TaskPriority::USER_VISIBLE}; |
| 150 template <class... ArgTypes, |
| 151 class CheckArgumentsAreValid = internal::InitTypes< |
| 152 decltype(ValidTrait(std::declval<ArgTypes>()))...>> |
| 153 constexpr TaskTraits(ArgTypes... args) |
| 154 : priority_set_explicitly_( |
| 155 internal::HasArgOfType<base::TaskPriority, ArgTypes...>::value), |
| 156 priority_(internal::GetValueFromArgList( |
| 157 internal::EnumArgGetter<base::TaskPriority, |
| 158 base::TaskPriority::USER_VISIBLE>(), |
| 159 args...)), |
| 160 shutdown_behavior_(internal::GetValueFromArgList( |
| 161 internal::EnumArgGetter< |
| 162 base::TaskShutdownBehavior, |
| 163 base::TaskShutdownBehavior::SKIP_ON_SHUTDOWN>(), |
| 164 args...)), |
| 165 may_block_(internal::GetValueFromArgList( |
| 166 internal::BooleanArgGetter<base::MayBlock>(), |
| 167 args...)), |
| 168 with_base_sync_primitives_(internal::GetValueFromArgList( |
| 169 internal::BooleanArgGetter<base::WithBaseSyncPrimitives>(), |
| 170 args...)) {} |
| 171 |
| 172 constexpr TaskTraits(const TaskTraits& other) = default; |
91 TaskTraits& operator=(const TaskTraits& other) = default; | 173 TaskTraits& operator=(const TaskTraits& other) = default; |
92 ~TaskTraits(); | |
93 | 174 |
94 // Tasks with this trait may block. This includes but is not limited to tasks | 175 // Deprecated. Prefer constexpr construction to builder paradigm as |
95 // that wait on synchronous file I/O operations: read or write a file from | 176 // documented above. |
96 // disk, interact with a pipe or a socket, rename or delete a file, enumerate | 177 // TODO(fdoray): Remove these methods. https://crbug.com/713683 |
97 // files in a directory, etc. This trait isn't required for the mere use of | 178 TaskTraits& WithPriority(TaskPriority priority); |
98 // locks. For tasks that block on base/ synchronization primitives, see | 179 TaskTraits& WithShutdownBehavior(TaskShutdownBehavior shutdown_behavior); |
99 // WithBaseSyncPrimitives(). | |
100 TaskTraits& MayBlock(); | 180 TaskTraits& MayBlock(); |
101 | |
102 // Tasks with this trait will pass base::AssertWaitAllowed(), i.e. will be | |
103 // allowed on the following methods : | |
104 // - base::WaitableEvent::Wait | |
105 // - base::ConditionVariable::Wait | |
106 // - base::PlatformThread::Join | |
107 // - base::PlatformThread::Sleep | |
108 // - base::Process::WaitForExit | |
109 // - base::Process::WaitForExitWithTimeout | |
110 // | |
111 // Tasks should generally not use these methods. | |
112 // | |
113 // Instead of waiting on a WaitableEvent or a ConditionVariable, put the work | |
114 // that should happen after the wait in a callback and post that callback from | |
115 // where the WaitableEvent or ConditionVariable would have been signaled. If | |
116 // something needs to be scheduled after many tasks have executed, use | |
117 // base::BarrierClosure. | |
118 // | |
119 // Avoid creating threads. Instead, use | |
120 // base::Create(Sequenced|SingleTreaded)TaskRunnerWithTraits(). If a thread is | |
121 // really needed, make it non-joinable and add cleanup work at the end of the | |
122 // thread's main function (if using base::Thread, override Cleanup()). | |
123 // | |
124 // On Windows, join processes asynchronously using base::win::ObjectWatcher. | |
125 // | |
126 // MayBlock() must be specified in conjunction with this trait if and only if | |
127 // removing usage of methods listed above in the labeled tasks would still | |
128 // result in tasks that may block (per MayBlock()'s definition). | |
129 // | |
130 // In doubt, consult with //base/task_scheduler/OWNERS. | |
131 TaskTraits& WithBaseSyncPrimitives(); | 181 TaskTraits& WithBaseSyncPrimitives(); |
132 | 182 |
133 // Applies |priority| to tasks with these traits. | 183 // Returns true if the priority was set explicitly. |
134 TaskTraits& WithPriority(TaskPriority priority); | 184 constexpr bool priority_set_explicitly() const { |
| 185 return priority_set_explicitly_; |
| 186 } |
135 | 187 |
136 // Applies |shutdown_behavior| to tasks with these traits. | 188 // Returns the priority of tasks with these traits. |
137 TaskTraits& WithShutdownBehavior(TaskShutdownBehavior shutdown_behavior); | 189 constexpr TaskPriority priority() const { return priority_; } |
| 190 |
| 191 // Returns the shutdown behavior of tasks with these traits. |
| 192 constexpr TaskShutdownBehavior shutdown_behavior() const { |
| 193 return shutdown_behavior_; |
| 194 } |
138 | 195 |
139 // Returns true if tasks with these traits may block. | 196 // Returns true if tasks with these traits may block. |
140 bool may_block() const { return may_block_; } | 197 constexpr bool may_block() const { return may_block_; } |
141 | 198 |
142 // Returns true if tasks with these traits may use base/ sync primitives. | 199 // Returns true if tasks with these traits may use base/ sync primitives. |
143 bool with_base_sync_primitives() const { return with_base_sync_primitives_; } | 200 constexpr bool with_base_sync_primitives() const { |
144 | 201 return with_base_sync_primitives_; |
145 // Returns true if the priority was set explicitly. | 202 } |
146 bool priority_set_explicitly() const { return priority_set_explicitly_; } | |
147 | |
148 // Returns the priority of tasks with these traits. | |
149 TaskPriority priority() const { return priority_; } | |
150 | |
151 // Returns the shutdown behavior of tasks with these traits. | |
152 TaskShutdownBehavior shutdown_behavior() const { return shutdown_behavior_; } | |
153 | 203 |
154 private: | 204 private: |
155 // Do not rely on defaults hard-coded below beyond the guarantees described on | 205 // TODO(fdoray): Make these const after refactoring away deprecated builder |
156 // the constructor; anything else is subject to change. Tasks should | 206 // pattern. |
157 // explicitly request defaults if the behavior is critical to the task. | 207 bool priority_set_explicitly_; |
158 bool may_block_ = false; | 208 TaskPriority priority_; |
159 bool with_base_sync_primitives_ = false; | 209 TaskShutdownBehavior shutdown_behavior_; |
160 bool priority_set_explicitly_ = false; | 210 bool may_block_; |
161 TaskPriority priority_ = TaskPriority::USER_VISIBLE; | 211 bool with_base_sync_primitives_; |
162 TaskShutdownBehavior shutdown_behavior_ = | |
163 TaskShutdownBehavior::SKIP_ON_SHUTDOWN; | |
164 }; | 212 }; |
165 | 213 |
166 // Returns string literals for the enums defined in this file. These methods | 214 // Returns string literals for the enums defined in this file. These methods |
167 // should only be used for tracing and debugging. | 215 // should only be used for tracing and debugging. |
168 BASE_EXPORT const char* TaskPriorityToString(TaskPriority task_priority); | 216 BASE_EXPORT const char* TaskPriorityToString(TaskPriority task_priority); |
169 BASE_EXPORT const char* TaskShutdownBehaviorToString( | 217 BASE_EXPORT const char* TaskShutdownBehaviorToString( |
170 TaskShutdownBehavior task_priority); | 218 TaskShutdownBehavior task_priority); |
171 | 219 |
172 // Stream operators so that the enums defined in this file can be used in | 220 // Stream operators so that the enums defined in this file can be used in |
173 // DCHECK and EXPECT statements. | 221 // DCHECK and EXPECT statements. |
174 BASE_EXPORT std::ostream& operator<<(std::ostream& os, | 222 BASE_EXPORT std::ostream& operator<<(std::ostream& os, |
175 const TaskPriority& shutdown_behavior); | 223 const TaskPriority& shutdown_behavior); |
176 BASE_EXPORT std::ostream& operator<<( | 224 BASE_EXPORT std::ostream& operator<<( |
177 std::ostream& os, | 225 std::ostream& os, |
178 const TaskShutdownBehavior& shutdown_behavior); | 226 const TaskShutdownBehavior& shutdown_behavior); |
179 | 227 |
180 } // namespace base | 228 } // namespace base |
181 | 229 |
182 #endif // BASE_TASK_SCHEDULER_TASK_TRAITS_H_ | 230 #endif // BASE_TASK_SCHEDULER_TASK_TRAITS_H_ |
OLD | NEW |