1 /* 2 * Copyright 2019 The WebRTC Project Authors. All rights reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 #ifndef API_TASK_QUEUE_TASK_QUEUE_BASE_H_ 11 #define API_TASK_QUEUE_TASK_QUEUE_BASE_H_ 12 13 #include <memory> 14 #include <utility> 15 16 #include "absl/functional/any_invocable.h" 17 #include "api/units/time_delta.h" 18 #include "rtc_base/system/rtc_export.h" 19 #include "rtc_base/thread_annotations.h" 20 21 namespace webrtc { 22 23 // Asynchronously executes tasks in a way that guarantees that they're executed 24 // in FIFO order and that tasks never overlap. Tasks may always execute on the 25 // same worker thread and they may not. To DCHECK that tasks are executing on a 26 // known task queue, use IsCurrent(). 27 class RTC_LOCKABLE RTC_EXPORT TaskQueueBase { 28 public: 29 enum class DelayPrecision { 30 // This may include up to a 17 ms leeway in addition to OS timer precision. 31 // See PostDelayedTask() for more information. 32 kLow, 33 // This does not have the additional delay that kLow has, but it is still 34 // limited by OS timer precision. See PostDelayedHighPrecisionTask() for 35 // more information. 36 kHigh, 37 }; 38 39 // Starts destruction of the task queue. 40 // On return ensures no task are running and no new tasks are able to start 41 // on the task queue. 42 // Responsible for deallocation. Deallocation may happen synchronously during 43 // Delete or asynchronously after Delete returns. 44 // Code not running on the TaskQueue should not make any assumption when 45 // TaskQueue is deallocated and thus should not call any methods after Delete. 46 // Code running on the TaskQueue should not call Delete, but can assume 47 // TaskQueue still exists and may call other methods, e.g. PostTask. 48 // Should be called on the same task queue or thread that this task queue 49 // was created on. 50 virtual void Delete() = 0; 51 52 // Schedules a `task` to execute. Tasks are executed in FIFO order. 53 // When a TaskQueue is deleted, pending tasks will not be executed but they 54 // will be deleted. The deletion of tasks may happen synchronously on the 55 // TaskQueue or it may happen asynchronously after TaskQueue is deleted. 56 // This may vary from one implementation to the next so assumptions about 57 // lifetimes of pending tasks should not be made. 58 // May be called on any thread or task queue, including this task queue. 59 virtual void PostTask(absl::AnyInvocable<void() &&> task) = 0; 60 61 // Prefer PostDelayedTask() over PostDelayedHighPrecisionTask() whenever 62 // possible. 63 // 64 // Schedules a `task` to execute a specified `delay` from when the call is 65 // made, using "low" precision. All scheduling is affected by OS-specific 66 // leeway and current workloads which means that in terms of precision there 67 // are no hard guarantees, but in addition to the OS induced leeway, "low" 68 // precision adds up to a 17 ms additional leeway. The purpose of this leeway 69 // is to achieve more efficient CPU scheduling and reduce Idle Wake Up 70 // frequency. 71 // 72 // The task may execute with [-1, 17 + OS induced leeway) ms additional delay. 73 // 74 // Avoid making assumptions about the precision of the OS scheduler. On macOS, 75 // the OS induced leeway may be 10% of sleep interval. On Windows, 1 ms 76 // precision timers may be used but there are cases, such as when running on 77 // battery, when the timer precision can be as poor as 15 ms. 78 // 79 // "Low" precision is not implemented everywhere yet. Where not yet 80 // implemented, PostDelayedTask() has "high" precision. See 81 // https://crbug.com/webrtc/13583 for more information. 82 // 83 // May be called on any thread or task queue, including this task queue. 84 virtual void PostDelayedTask(absl::AnyInvocable<void() &&> task, 85 TimeDelta delay) = 0; 86 87 // Prefer PostDelayedTask() over PostDelayedHighPrecisionTask() whenever 88 // possible. 89 // 90 // Schedules a `task` to execute a specified `delay` from when the call is 91 // made, using "high" precision. All scheduling is affected by OS-specific 92 // leeway and current workloads which means that in terms of precision there 93 // are no hard guarantees. 94 // 95 // The task may execute with [-1, OS induced leeway] ms additional delay. 96 // 97 // Avoid making assumptions about the precision of the OS scheduler. On macOS, 98 // the OS induced leeway may be 10% of sleep interval. On Windows, 1 ms 99 // precision timers may be used but there are cases, such as when running on 100 // battery, when the timer precision can be as poor as 15 ms. 101 // 102 // May be called on any thread or task queue, including this task queue. 103 virtual void PostDelayedHighPrecisionTask(absl::AnyInvocable<void() &&> task, 104 TimeDelta delay) = 0; 105 106 // As specified by `precision`, calls either PostDelayedTask() or 107 // PostDelayedHighPrecisionTask(). PostDelayedTaskWithPrecision(DelayPrecision precision,absl::AnyInvocable<void ()&&> task,TimeDelta delay)108 void PostDelayedTaskWithPrecision(DelayPrecision precision, 109 absl::AnyInvocable<void() &&> task, 110 TimeDelta delay) { 111 switch (precision) { 112 case DelayPrecision::kLow: 113 PostDelayedTask(std::move(task), delay); 114 break; 115 case DelayPrecision::kHigh: 116 PostDelayedHighPrecisionTask(std::move(task), delay); 117 break; 118 } 119 } 120 121 // Returns the task queue that is running the current thread. 122 // Returns nullptr if this thread is not associated with any task queue. 123 // May be called on any thread or task queue, including this task queue. 124 static TaskQueueBase* Current(); IsCurrent()125 bool IsCurrent() const { return Current() == this; } 126 127 protected: 128 class RTC_EXPORT CurrentTaskQueueSetter { 129 public: 130 explicit CurrentTaskQueueSetter(TaskQueueBase* task_queue); 131 CurrentTaskQueueSetter(const CurrentTaskQueueSetter&) = delete; 132 CurrentTaskQueueSetter& operator=(const CurrentTaskQueueSetter&) = delete; 133 ~CurrentTaskQueueSetter(); 134 135 private: 136 TaskQueueBase* const previous_; 137 }; 138 139 // Users of the TaskQueue should call Delete instead of directly deleting 140 // this object. 141 virtual ~TaskQueueBase() = default; 142 }; 143 144 struct TaskQueueDeleter { operatorTaskQueueDeleter145 void operator()(TaskQueueBase* task_queue) const { task_queue->Delete(); } 146 }; 147 148 } // namespace webrtc 149 150 #endif // API_TASK_QUEUE_TASK_QUEUE_BASE_H_ 151