tommi | c06b133 | 2016-05-14 11:31:40 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2016 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 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 11 | #ifndef RTC_BASE_TASK_QUEUE_H_ |
| 12 | #define RTC_BASE_TASK_QUEUE_H_ |
tommi | c06b133 | 2016-05-14 11:31:40 -0700 | [diff] [blame] | 13 | |
Yves Gerey | 3e70781 | 2018-11-28 16:47:49 +0100 | [diff] [blame] | 14 | #include <stdint.h> |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 15 | #include <memory> |
eladalon | ffe2e14 | 2017-08-31 04:36:05 -0700 | [diff] [blame] | 16 | #include <type_traits> |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 17 | #include <utility> |
tommi | c06b133 | 2016-05-14 11:31:40 -0700 | [diff] [blame] | 18 | |
Karl Wiberg | 918f50c | 2018-07-05 11:40:33 +0200 | [diff] [blame] | 19 | #include "absl/memory/memory.h" |
Danil Chapovalov | 959e9b6 | 2019-01-14 14:29:18 +0100 | [diff] [blame] | 20 | #include "api/task_queue/queued_task.h" |
Steve Anton | 10542f2 | 2019-01-11 09:11:00 -0800 | [diff] [blame] | 21 | #include "rtc_base/constructor_magic.h" |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 22 | #include "rtc_base/scoped_ref_ptr.h" |
Mirko Bonadei | 3d25530 | 2018-10-11 10:50:45 +0200 | [diff] [blame] | 23 | #include "rtc_base/system/rtc_export.h" |
Danil Chapovalov | 02fddf6 | 2018-02-12 12:41:16 +0100 | [diff] [blame] | 24 | #include "rtc_base/thread_annotations.h" |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 25 | |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 26 | namespace rtc { |
| 27 | |
Danil Chapovalov | 959e9b6 | 2019-01-14 14:29:18 +0100 | [diff] [blame] | 28 | // TODO(danilchap): Remove the alias when all of webrtc is updated to use |
| 29 | // webrtc::QueuedTask directly. |
| 30 | using ::webrtc::QueuedTask; |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 31 | |
| 32 | // Simple implementation of QueuedTask for use with rtc::Bind and lambdas. |
| 33 | template <class Closure> |
| 34 | class ClosureTask : public QueuedTask { |
| 35 | public: |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 36 | explicit ClosureTask(Closure&& closure) |
| 37 | : closure_(std::forward<Closure>(closure)) {} |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 38 | |
| 39 | private: |
| 40 | bool Run() override { |
| 41 | closure_(); |
| 42 | return true; |
| 43 | } |
| 44 | |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 45 | typename std::remove_const< |
| 46 | typename std::remove_reference<Closure>::type>::type closure_; |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 47 | }; |
| 48 | |
| 49 | // Extends ClosureTask to also allow specifying cleanup code. |
| 50 | // This is useful when using lambdas if guaranteeing cleanup, even if a task |
| 51 | // was dropped (queue is too full), is required. |
| 52 | template <class Closure, class Cleanup> |
| 53 | class ClosureTaskWithCleanup : public ClosureTask<Closure> { |
| 54 | public: |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 55 | ClosureTaskWithCleanup(Closure&& closure, Cleanup&& cleanup) |
| 56 | : ClosureTask<Closure>(std::forward<Closure>(closure)), |
| 57 | cleanup_(std::forward<Cleanup>(cleanup)) {} |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 58 | ~ClosureTaskWithCleanup() { cleanup_(); } |
| 59 | |
| 60 | private: |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 61 | typename std::remove_const< |
| 62 | typename std::remove_reference<Cleanup>::type>::type cleanup_; |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 63 | }; |
| 64 | |
| 65 | // Convenience function to construct closures that can be passed directly |
| 66 | // to methods that support std::unique_ptr<QueuedTask> but not template |
| 67 | // based parameters. |
| 68 | template <class Closure> |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 69 | static std::unique_ptr<QueuedTask> NewClosure(Closure&& closure) { |
Karl Wiberg | 918f50c | 2018-07-05 11:40:33 +0200 | [diff] [blame] | 70 | return absl::make_unique<ClosureTask<Closure>>( |
| 71 | std::forward<Closure>(closure)); |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 72 | } |
| 73 | |
| 74 | template <class Closure, class Cleanup> |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 75 | static std::unique_ptr<QueuedTask> NewClosure(Closure&& closure, |
| 76 | Cleanup&& cleanup) { |
Karl Wiberg | 918f50c | 2018-07-05 11:40:33 +0200 | [diff] [blame] | 77 | return absl::make_unique<ClosureTaskWithCleanup<Closure, Cleanup>>( |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 78 | std::forward<Closure>(closure), std::forward<Cleanup>(cleanup)); |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 79 | } |
| 80 | |
| 81 | // Implements a task queue that asynchronously executes tasks in a way that |
| 82 | // guarantees that they're executed in FIFO order and that tasks never overlap. |
| 83 | // Tasks may always execute on the same worker thread and they may not. |
| 84 | // To DCHECK that tasks are executing on a known task queue, use IsCurrent(). |
| 85 | // |
| 86 | // Here are some usage examples: |
| 87 | // |
| 88 | // 1) Asynchronously running a lambda: |
| 89 | // |
| 90 | // class MyClass { |
| 91 | // ... |
| 92 | // TaskQueue queue_("MyQueue"); |
| 93 | // }; |
| 94 | // |
| 95 | // void MyClass::StartWork() { |
| 96 | // queue_.PostTask([]() { Work(); }); |
| 97 | // ... |
| 98 | // |
| 99 | // 2) Doing work asynchronously on a worker queue and providing a notification |
| 100 | // callback on the current queue, when the work has been done: |
| 101 | // |
| 102 | // void MyClass::StartWorkAndLetMeKnowWhenDone( |
| 103 | // std::unique_ptr<QueuedTask> callback) { |
| 104 | // DCHECK(TaskQueue::Current()) << "Need to be running on a queue"; |
| 105 | // queue_.PostTaskAndReply([]() { Work(); }, std::move(callback)); |
| 106 | // } |
| 107 | // ... |
| 108 | // my_class->StartWorkAndLetMeKnowWhenDone( |
Mirko Bonadei | 675513b | 2017-11-09 11:09:25 +0100 | [diff] [blame] | 109 | // NewClosure([]() { RTC_LOG(INFO) << "The work is done!";})); |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 110 | // |
| 111 | // 3) Posting a custom task on a timer. The task posts itself again after |
| 112 | // every running: |
| 113 | // |
| 114 | // class TimerTask : public QueuedTask { |
| 115 | // public: |
| 116 | // TimerTask() {} |
| 117 | // private: |
| 118 | // bool Run() override { |
| 119 | // ++count_; |
| 120 | // TaskQueue::Current()->PostDelayedTask( |
| 121 | // std::unique_ptr<QueuedTask>(this), 1000); |
| 122 | // // Ownership has been transferred to the next occurance, |
| 123 | // // so return false to prevent from being deleted now. |
| 124 | // return false; |
| 125 | // } |
| 126 | // int count_ = 0; |
| 127 | // }; |
| 128 | // ... |
| 129 | // queue_.PostDelayedTask( |
| 130 | // std::unique_ptr<QueuedTask>(new TimerTask()), 1000); |
| 131 | // |
| 132 | // For more examples, see task_queue_unittests.cc. |
| 133 | // |
| 134 | // A note on destruction: |
| 135 | // |
| 136 | // When a TaskQueue is deleted, pending tasks will not be executed but they will |
| 137 | // be deleted. The deletion of tasks may happen asynchronously after the |
| 138 | // TaskQueue itself has been deleted or it may happen synchronously while the |
| 139 | // TaskQueue instance is being deleted. This may vary from one OS to the next |
| 140 | // so assumptions about lifetimes of pending tasks should not be made. |
Mirko Bonadei | 3d25530 | 2018-10-11 10:50:45 +0200 | [diff] [blame] | 141 | class RTC_LOCKABLE RTC_EXPORT TaskQueue { |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 142 | public: |
| 143 | // TaskQueue priority levels. On some platforms these will map to thread |
| 144 | // priorities, on others such as Mac and iOS, GCD queue priorities. |
| 145 | enum class Priority { |
| 146 | NORMAL = 0, |
| 147 | HIGH, |
| 148 | LOW, |
| 149 | }; |
| 150 | |
| 151 | explicit TaskQueue(const char* queue_name, |
| 152 | Priority priority = Priority::NORMAL); |
| 153 | ~TaskQueue(); |
| 154 | |
| 155 | static TaskQueue* Current(); |
| 156 | |
| 157 | // Used for DCHECKing the current queue. |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 158 | bool IsCurrent() const; |
| 159 | |
| 160 | // TODO(tommi): For better debuggability, implement RTC_FROM_HERE. |
| 161 | |
| 162 | // Ownership of the task is passed to PostTask. |
| 163 | void PostTask(std::unique_ptr<QueuedTask> task); |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 164 | |
| 165 | // Schedules a task to execute a specified number of milliseconds from when |
| 166 | // the call is made. The precision should be considered as "best effort" |
| 167 | // and in some cases, such as on Windows when all high precision timers have |
| 168 | // been used up, can be off by as much as 15 millseconds (although 8 would be |
| 169 | // more likely). This can be mitigated by limiting the use of delayed tasks. |
| 170 | void PostDelayedTask(std::unique_ptr<QueuedTask> task, uint32_t milliseconds); |
| 171 | |
eladalon | ffe2e14 | 2017-08-31 04:36:05 -0700 | [diff] [blame] | 172 | // std::enable_if is used here to make sure that calls to PostTask() with |
| 173 | // std::unique_ptr<SomeClassDerivedFromQueuedTask> would not end up being |
| 174 | // caught by this template. |
| 175 | template <class Closure, |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 176 | typename std::enable_if<!std::is_convertible< |
| 177 | Closure, |
| 178 | std::unique_ptr<QueuedTask>>::value>::type* = nullptr> |
| 179 | void PostTask(Closure&& closure) { |
| 180 | PostTask(NewClosure(std::forward<Closure>(closure))); |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 181 | } |
| 182 | |
| 183 | // See documentation above for performance expectations. |
Danil Chapovalov | 6f09ae2 | 2017-10-12 14:39:25 +0200 | [diff] [blame] | 184 | template <class Closure, |
| 185 | typename std::enable_if<!std::is_convertible< |
| 186 | Closure, |
| 187 | std::unique_ptr<QueuedTask>>::value>::type* = nullptr> |
| 188 | void PostDelayedTask(Closure&& closure, uint32_t milliseconds) { |
| 189 | PostDelayedTask(NewClosure(std::forward<Closure>(closure)), milliseconds); |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 190 | } |
| 191 | |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 192 | private: |
perkj | 650fdae | 2017-08-25 05:00:11 -0700 | [diff] [blame] | 193 | class Impl; |
Danil Chapovalov | 43f3982 | 2018-12-05 15:46:58 +0100 | [diff] [blame] | 194 | // TODO(danilchap): Remove when external implementaions of TaskQueue remove |
| 195 | // these two functions. |
| 196 | void PostTaskAndReply(std::unique_ptr<QueuedTask> task, |
| 197 | std::unique_ptr<QueuedTask> reply, |
| 198 | TaskQueue* reply_queue); |
| 199 | void PostTaskAndReply(std::unique_ptr<QueuedTask> task, |
| 200 | std::unique_ptr<QueuedTask> reply); |
Yves Gerey | 3e70781 | 2018-11-28 16:47:49 +0100 | [diff] [blame] | 201 | |
perkj | 650fdae | 2017-08-25 05:00:11 -0700 | [diff] [blame] | 202 | const scoped_refptr<Impl> impl_; |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 203 | |
| 204 | RTC_DISALLOW_COPY_AND_ASSIGN(TaskQueue); |
| 205 | }; |
| 206 | |
| 207 | } // namespace rtc |
tommi | c06b133 | 2016-05-14 11:31:40 -0700 | [diff] [blame] | 208 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 209 | #endif // RTC_BASE_TASK_QUEUE_H_ |