tommi | c06b133 | 2016-05-14 18:31:40 | [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 04:47:31 | [diff] [blame] | 11 | #ifndef RTC_BASE_TASK_QUEUE_H_ |
| 12 | #define RTC_BASE_TASK_QUEUE_H_ |
tommi | c06b133 | 2016-05-14 18:31:40 | [diff] [blame] | 13 | |
Yves Gerey | 3e70781 | 2018-11-28 15:47:49 | [diff] [blame] | 14 | #include <stdint.h> |
Jonas Olsson | a4d8737 | 2019-07-05 17:08:33 | [diff] [blame] | 15 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 16 | #include <memory> |
Danil Chapovalov | 6f09ae2 | 2017-10-12 12:39:25 | [diff] [blame] | 17 | #include <utility> |
tommi | c06b133 | 2016-05-14 18:31:40 | [diff] [blame] | 18 | |
Danil Chapovalov | a7e15a2 | 2022-07-05 14:03:03 | [diff] [blame] | 19 | #include "absl/functional/any_invocable.h" |
Karl Wiberg | 918f50c | 2018-07-05 09:40:33 | [diff] [blame] | 20 | #include "absl/memory/memory.h" |
Danil Chapovalov | d00405f | 2019-02-25 14:06:13 | [diff] [blame] | 21 | #include "api/task_queue/task_queue_base.h" |
| 22 | #include "api/task_queue/task_queue_factory.h" |
Mirko Bonadei | 3d25530 | 2018-10-11 08:50:45 | [diff] [blame] | 23 | #include "rtc_base/system/rtc_export.h" |
Danil Chapovalov | 02fddf6 | 2018-02-12 11:41:16 | [diff] [blame] | 24 | #include "rtc_base/thread_annotations.h" |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 25 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 26 | namespace rtc { |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 27 | // Implements a task queue that asynchronously executes tasks in a way that |
| 28 | // guarantees that they're executed in FIFO order and that tasks never overlap. |
| 29 | // Tasks may always execute on the same worker thread and they may not. |
| 30 | // To DCHECK that tasks are executing on a known task queue, use IsCurrent(). |
| 31 | // |
| 32 | // Here are some usage examples: |
| 33 | // |
| 34 | // 1) Asynchronously running a lambda: |
| 35 | // |
| 36 | // class MyClass { |
| 37 | // ... |
| 38 | // TaskQueue queue_("MyQueue"); |
| 39 | // }; |
| 40 | // |
| 41 | // void MyClass::StartWork() { |
| 42 | // queue_.PostTask([]() { Work(); }); |
| 43 | // ... |
| 44 | // |
Danil Chapovalov | 1aa7581 | 2019-03-05 10:11:35 | [diff] [blame] | 45 | // 2) Posting a custom task on a timer. The task posts itself again after |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 46 | // every running: |
| 47 | // |
| 48 | // class TimerTask : public QueuedTask { |
| 49 | // public: |
| 50 | // TimerTask() {} |
| 51 | // private: |
| 52 | // bool Run() override { |
| 53 | // ++count_; |
Danil Chapovalov | ad89528 | 2019-03-11 10:28:05 | [diff] [blame] | 54 | // TaskQueueBase::Current()->PostDelayedTask( |
| 55 | // absl::WrapUnique(this), 1000); |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 56 | // // Ownership has been transferred to the next occurance, |
| 57 | // // so return false to prevent from being deleted now. |
| 58 | // return false; |
| 59 | // } |
| 60 | // int count_ = 0; |
| 61 | // }; |
| 62 | // ... |
Mirko Bonadei | 317a1f0 | 2019-09-17 15:06:18 | [diff] [blame] | 63 | // queue_.PostDelayedTask(std::make_unique<TimerTask>(), 1000); |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 64 | // |
| 65 | // For more examples, see task_queue_unittests.cc. |
| 66 | // |
| 67 | // A note on destruction: |
| 68 | // |
| 69 | // When a TaskQueue is deleted, pending tasks will not be executed but they will |
| 70 | // be deleted. The deletion of tasks may happen asynchronously after the |
| 71 | // TaskQueue itself has been deleted or it may happen synchronously while the |
| 72 | // TaskQueue instance is being deleted. This may vary from one OS to the next |
| 73 | // so assumptions about lifetimes of pending tasks should not be made. |
Mirko Bonadei | 3d25530 | 2018-10-11 08:50:45 | [diff] [blame] | 74 | class RTC_LOCKABLE RTC_EXPORT TaskQueue { |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 75 | public: |
| 76 | // TaskQueue priority levels. On some platforms these will map to thread |
| 77 | // priorities, on others such as Mac and iOS, GCD queue priorities. |
Danil Chapovalov | d00405f | 2019-02-25 14:06:13 | [diff] [blame] | 78 | using Priority = ::webrtc::TaskQueueFactory::Priority; |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 79 | |
Danil Chapovalov | f3280e9 | 2019-02-28 09:39:04 | [diff] [blame] | 80 | explicit TaskQueue(std::unique_ptr<webrtc::TaskQueueBase, |
| 81 | webrtc::TaskQueueDeleter> task_queue); |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 82 | ~TaskQueue(); |
| 83 | |
Byoungchan Lee | 14af762 | 2022-01-11 20:24:58 | [diff] [blame] | 84 | TaskQueue(const TaskQueue&) = delete; |
| 85 | TaskQueue& operator=(const TaskQueue&) = delete; |
| 86 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 87 | // Used for DCHECKing the current queue. |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 88 | bool IsCurrent() const; |
| 89 | |
Danil Chapovalov | f3280e9 | 2019-02-28 09:39:04 | [diff] [blame] | 90 | // Returns non-owning pointer to the task queue implementation. |
| 91 | webrtc::TaskQueueBase* Get() { return impl_; } |
| 92 | |
Markus Handell | 2fa39bd | 2023-03-01 13:00:12 | [diff] [blame] | 93 | void PostTask( |
| 94 | absl::AnyInvocable<void() &&> task, |
| 95 | const webrtc::Location& location = webrtc::Location::Current()) { |
| 96 | impl_->PostTask(std::move(task), location); |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 97 | } |
Markus Handell | 2fa39bd | 2023-03-01 13:00:12 | [diff] [blame] | 98 | void PostDelayedTask( |
| 99 | absl::AnyInvocable<void() &&> task, |
| 100 | webrtc::TimeDelta delay, |
| 101 | const webrtc::Location& location = webrtc::Location::Current()) { |
| 102 | impl_->PostDelayedTask(std::move(task), delay, location); |
Danil Chapovalov | c05a1be | 2022-07-19 11:07:12 | [diff] [blame] | 103 | } |
Markus Handell | 2fa39bd | 2023-03-01 13:00:12 | [diff] [blame] | 104 | void PostDelayedHighPrecisionTask( |
| 105 | absl::AnyInvocable<void() &&> task, |
| 106 | webrtc::TimeDelta delay, |
| 107 | const webrtc::Location& location = webrtc::Location::Current()) { |
| 108 | impl_->PostDelayedHighPrecisionTask(std::move(task), delay, location); |
Danil Chapovalov | c05a1be | 2022-07-19 11:07:12 | [diff] [blame] | 109 | } |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 110 | |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 111 | private: |
Danil Chapovalov | d00405f | 2019-02-25 14:06:13 | [diff] [blame] | 112 | webrtc::TaskQueueBase* const impl_; |
Henrik Kjellander | ec78f1c | 2017-06-29 05:52:50 | [diff] [blame] | 113 | }; |
| 114 | |
| 115 | } // namespace rtc |
tommi | c06b133 | 2016-05-14 18:31:40 | [diff] [blame] | 116 | |
Mirko Bonadei | 92ea95e | 2017-09-15 04:47:31 | [diff] [blame] | 117 | #endif // RTC_BASE_TASK_QUEUE_H_ |