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 3 // found in the LICENSE file. 4 5 #ifndef BASE_TASK_SCHEDULER_TASK_TRAITS_H_ 6 #define BASE_TASK_SCHEDULER_TASK_TRAITS_H_ 7 8 #include <stdint.h> 9 10 #include <iosfwd> 11 12 #include "base/base_export.h" 13 #include "build/build_config.h" 14 15 namespace base { 16 17 // Valid priorities supported by the task scheduler. Note: internal algorithms 18 // 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 20 // nor use the underlying values. 21 enum class TaskPriority { 22 // This will always be equal to the lowest priority available. 23 LOWEST = 0, 24 // User won't notice if this task takes an arbitrarily long time to complete. 25 BACKGROUND = LOWEST, 26 // This task affects UI or responsiveness of future user interactions. It is 27 // not an immediate response to a user interaction. 28 // Examples: 29 // - Updating the UI to reflect progress on a long task. 30 // - Loading data that might be shown in the UI after a future user 31 // interaction. 32 USER_VISIBLE, 33 // This task affects UI immediately after a user interaction. 34 // Example: Generating data shown in the UI immediately after a click. 35 USER_BLOCKING, 36 // This will always be equal to the highest priority available. 37 HIGHEST = USER_BLOCKING, 38 }; 39 40 // Valid shutdown behaviors supported by the task scheduler. 41 enum class TaskShutdownBehavior { 42 // Tasks posted with this mode which have not started executing before 43 // shutdown is initiated will never run. Tasks with this mode running at 44 // shutdown will be ignored (the worker will not be joined). 45 // 46 // This option provides a nice way to post stuff you don't want blocking 47 // shutdown. For example, you might be doing a slow DNS lookup and if it's 48 // blocked on the OS, you may not want to stop shutdown, since the result 49 // doesn't really matter at that point. 50 // 51 // However, you need to be very careful what you do in your callback when you 52 // use this option. Since the thread will continue to run until the OS 53 // terminates the process, the app can be in the process of tearing down when 54 // you're running. This means any singletons or global objects you use may 55 // suddenly become invalid out from under you. For this reason, it's best to 56 // use this only for slow but simple operations like the DNS example. 57 CONTINUE_ON_SHUTDOWN, 58 59 // Tasks posted with this mode that have not started executing at 60 // shutdown will never run. However, any task that has already begun 61 // executing when shutdown is invoked will be allowed to continue and 62 // will block shutdown until completion. 63 // 64 // Note: Because TaskScheduler::Shutdown() may block while these tasks are 65 // executing, care must be taken to ensure that they do not block on the 66 // thread that called TaskScheduler::Shutdown(), as this may lead to deadlock. 67 SKIP_ON_SHUTDOWN, 68 69 // 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 71 // critical user data. 72 // 73 // Note: Tasks with BACKGROUND priority that block shutdown will be promoted 74 // to USER_VISIBLE priority during shutdown. 75 BLOCK_SHUTDOWN, 76 }; 77 78 // Describes metadata for a single task or a group of tasks. 79 class BASE_EXPORT TaskTraits { 80 public: 81 // Constructs a default TaskTraits for tasks with 82 // (1) no I/O, 83 // (2) low priority, and 84 // (3) may block shutdown or be skipped on shutdown. 85 // Tasks that require stricter guarantees should highlight those by requesting 86 // explicit traits below. 87 TaskTraits(); 88 TaskTraits(const TaskTraits& other) = default; 89 TaskTraits& operator=(const TaskTraits& other) = default; 90 ~TaskTraits(); 91 92 // Allows tasks with these traits to do file I/O. 93 TaskTraits& WithFileIO(); 94 95 // Applies |priority| to tasks with these traits. 96 TaskTraits& WithPriority(TaskPriority priority); 97 98 // Applies |shutdown_behavior| to tasks with these traits. 99 TaskTraits& WithShutdownBehavior(TaskShutdownBehavior shutdown_behavior); 100 101 // Returns true if file I/O is allowed by these traits. with_file_io()102 bool with_file_io() const { return with_file_io_; } 103 104 // Returns the priority of tasks with these traits. priority()105 TaskPriority priority() const { return priority_; } 106 107 // Returns the shutdown behavior of tasks with these traits. shutdown_behavior()108 TaskShutdownBehavior shutdown_behavior() const { return shutdown_behavior_; } 109 110 private: 111 bool with_file_io_; 112 TaskPriority priority_; 113 TaskShutdownBehavior shutdown_behavior_; 114 }; 115 116 // Describes how tasks are executed by a task runner. 117 enum class ExecutionMode { 118 // Can execute multiple tasks at a time in any order. 119 PARALLEL, 120 121 // Executes one task at a time in posting order. The sequence’s priority is 122 // equivalent to the highest priority pending task in the sequence. 123 SEQUENCED, 124 125 // Executes one task at a time on a single thread in posting order. 126 SINGLE_THREADED, 127 }; 128 129 // Stream operators so TaskPriority and TaskShutdownBehavior can be used in 130 // DCHECK statements. 131 BASE_EXPORT std::ostream& operator<<(std::ostream& os, 132 const TaskPriority& shutdown_behavior); 133 134 BASE_EXPORT std::ostream& operator<<( 135 std::ostream& os, 136 const TaskShutdownBehavior& shutdown_behavior); 137 138 } // namespace base 139 140 #endif // BASE_TASK_SCHEDULER_TASK_TRAITS_H_ 141