blob: e52c49cf008428bbfbd9ac91143b14ba71e30af5 [file] [log] [blame]
tommic06b1332016-05-14 18:31:401/*
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 Bonadei92ea95e2017-09-15 04:47:3111#ifndef RTC_BASE_TASK_QUEUE_H_
12#define RTC_BASE_TASK_QUEUE_H_
tommic06b1332016-05-14 18:31:4013
Yves Gerey3e707812018-11-28 15:47:4914#include <stdint.h>
Jonas Olssona4d87372019-07-05 17:08:3315
Henrik Kjellanderec78f1c2017-06-29 05:52:5016#include <memory>
Danil Chapovalov6f09ae22017-10-12 12:39:2517#include <utility>
tommic06b1332016-05-14 18:31:4018
Danil Chapovalova7e15a22022-07-05 14:03:0319#include "absl/functional/any_invocable.h"
Karl Wiberg918f50c2018-07-05 09:40:3320#include "absl/memory/memory.h"
Danil Chapovalovd00405f2019-02-25 14:06:1321#include "api/task_queue/task_queue_base.h"
22#include "api/task_queue/task_queue_factory.h"
Mirko Bonadei3d255302018-10-11 08:50:4523#include "rtc_base/system/rtc_export.h"
Danil Chapovalov02fddf62018-02-12 11:41:1624#include "rtc_base/thread_annotations.h"
Henrik Kjellanderec78f1c2017-06-29 05:52:5025
Henrik Kjellanderec78f1c2017-06-29 05:52:5026namespace rtc {
Henrik Kjellanderec78f1c2017-06-29 05:52:5027// 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 Chapovalov1aa75812019-03-05 10:11:3545// 2) Posting a custom task on a timer. The task posts itself again after
Henrik Kjellanderec78f1c2017-06-29 05:52:5046// every running:
47//
48// class TimerTask : public QueuedTask {
49// public:
50// TimerTask() {}
51// private:
52// bool Run() override {
53// ++count_;
Danil Chapovalovad895282019-03-11 10:28:0554// TaskQueueBase::Current()->PostDelayedTask(
55// absl::WrapUnique(this), 1000);
Henrik Kjellanderec78f1c2017-06-29 05:52:5056// // 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 Bonadei317a1f02019-09-17 15:06:1863// queue_.PostDelayedTask(std::make_unique<TimerTask>(), 1000);
Henrik Kjellanderec78f1c2017-06-29 05:52:5064//
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 Bonadei3d255302018-10-11 08:50:4574class RTC_LOCKABLE RTC_EXPORT TaskQueue {
Henrik Kjellanderec78f1c2017-06-29 05:52:5075 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 Chapovalovd00405f2019-02-25 14:06:1378 using Priority = ::webrtc::TaskQueueFactory::Priority;
Henrik Kjellanderec78f1c2017-06-29 05:52:5079
Danil Chapovalovf3280e92019-02-28 09:39:0480 explicit TaskQueue(std::unique_ptr<webrtc::TaskQueueBase,
81 webrtc::TaskQueueDeleter> task_queue);
Henrik Kjellanderec78f1c2017-06-29 05:52:5082 ~TaskQueue();
83
Byoungchan Lee14af7622022-01-11 20:24:5884 TaskQueue(const TaskQueue&) = delete;
85 TaskQueue& operator=(const TaskQueue&) = delete;
86
Henrik Kjellanderec78f1c2017-06-29 05:52:5087 // Used for DCHECKing the current queue.
Henrik Kjellanderec78f1c2017-06-29 05:52:5088 bool IsCurrent() const;
89
Danil Chapovalovf3280e92019-02-28 09:39:0490 // Returns non-owning pointer to the task queue implementation.
91 webrtc::TaskQueueBase* Get() { return impl_; }
92
Markus Handell2fa39bd2023-03-01 13:00:1293 void PostTask(
94 absl::AnyInvocable<void() &&> task,
95 const webrtc::Location& location = webrtc::Location::Current()) {
96 impl_->PostTask(std::move(task), location);
Henrik Kjellanderec78f1c2017-06-29 05:52:5097 }
Markus Handell2fa39bd2023-03-01 13:00:1298 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 Chapovalovc05a1be2022-07-19 11:07:12103 }
Markus Handell2fa39bd2023-03-01 13:00:12104 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 Chapovalovc05a1be2022-07-19 11:07:12109 }
Henrik Kjellanderec78f1c2017-06-29 05:52:50110
Henrik Kjellanderec78f1c2017-06-29 05:52:50111 private:
Danil Chapovalovd00405f2019-02-25 14:06:13112 webrtc::TaskQueueBase* const impl_;
Henrik Kjellanderec78f1c2017-06-29 05:52:50113};
114
115} // namespace rtc
tommic06b1332016-05-14 18:31:40116
Mirko Bonadei92ea95e2017-09-15 04:47:31117#endif // RTC_BASE_TASK_QUEUE_H_