blob: 20b24f3314a66991512d80906613da0f77b045e4 [file] [log] [blame]
henrike@webrtc.orgf0488722014-05-13 18:00:26 +00001/*
2 * Copyright 2014 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
Steve Anton10542f22019-01-11 09:11:00 -080011#ifndef RTC_BASE_ASYNC_INVOKER_H_
12#define RTC_BASE_ASYNC_INVOKER_H_
henrike@webrtc.orgf0488722014-05-13 18:00:26 +000013
deadbeef3af63b02017-08-08 17:59:47 -070014#include <atomic>
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +020015#include <memory>
16#include <utility>
deadbeefa8bc1a12017-02-17 18:06:26 -080017
Niels Möller0694ce72021-05-03 16:03:22 +020018#include "absl/base/attributes.h"
Mirko Bonadeid9708072019-01-25 20:26:48 +010019#include "api/scoped_refptr.h"
Steve Anton10542f22019-01-11 09:11:00 -080020#include "rtc_base/async_invoker_inl.h"
Steve Anton10542f22019-01-11 09:11:00 -080021#include "rtc_base/constructor_magic.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020022#include "rtc_base/event.h"
Steve Anton10542f22019-01-11 09:11:00 -080023#include "rtc_base/ref_counted_object.h"
Artem Titove41c4332018-07-25 15:04:28 +020024#include "rtc_base/third_party/sigslot/sigslot.h"
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020025#include "rtc_base/thread.h"
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +020026
27namespace rtc {
28
29// Invokes function objects (aka functors) asynchronously on a Thread, and
30// owns the lifetime of calls (ie, when this object is destroyed, calls in
31// flight are cancelled). AsyncInvoker can optionally execute a user-specified
32// function when the asynchronous call is complete, or operates in
33// fire-and-forget mode otherwise.
34//
35// AsyncInvoker does not own the thread it calls functors on.
36//
37// A note about async calls and object lifetimes: users should
38// be mindful of object lifetimes when calling functions asynchronously and
39// ensure objects used by the function _cannot_ be deleted between the
40// invocation and execution of the functor. AsyncInvoker is designed to
41// help: any calls in flight will be cancelled when the AsyncInvoker used to
42// make the call is destructed, and any calls executing will be allowed to
43// complete before AsyncInvoker destructs.
44//
45// The easiest way to ensure lifetimes are handled correctly is to create a
46// class that owns the Thread and AsyncInvoker objects, and then call its
47// methods asynchronously as needed.
48//
49// Example:
50// class MyClass {
51// public:
52// void FireAsyncTaskWithResult(Thread* thread, int x) {
53// // Specify a callback to get the result upon completion.
54// invoker_.AsyncInvoke<int>(RTC_FROM_HERE,
55// thread, Bind(&MyClass::AsyncTaskWithResult, this, x),
56// &MyClass::OnTaskComplete, this);
57// }
58// void FireAnotherAsyncTask(Thread* thread) {
59// // No callback specified means fire-and-forget.
60// invoker_.AsyncInvoke<void>(RTC_FROM_HERE,
61// thread, Bind(&MyClass::AnotherAsyncTask, this));
62//
63// private:
64// int AsyncTaskWithResult(int x) {
65// // Some long running process...
66// return x * x;
67// }
68// void AnotherAsyncTask() {
69// // Some other long running process...
70// }
71// void OnTaskComplete(int result) { result_ = result; }
72//
73// AsyncInvoker invoker_;
74// int result_;
75// };
deadbeef3af63b02017-08-08 17:59:47 -070076//
77// More details about threading:
78// - It's safe to construct/destruct AsyncInvoker on different threads.
79// - It's safe to call AsyncInvoke from different threads.
80// - It's safe to call AsyncInvoke recursively from *within* a functor that's
81// being AsyncInvoked.
82// - However, it's *not* safe to call AsyncInvoke from *outside* a functor
83// that's being AsyncInvoked while the AsyncInvoker is being destroyed on
84// another thread. This is just inherently unsafe and there's no way to
85// prevent that. So, the user of this class should ensure that the start of
86// each "chain" of invocations is synchronized somehow with the AsyncInvoker's
87// destruction. This can be done by starting each chain of invocations on the
88// same thread on which it will be destroyed, or by using some other
89// synchronization method.
Niels Möller0694ce72021-05-03 16:03:22 +020090class DEPRECATED_AsyncInvoker : public MessageHandlerAutoCleanup {
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +020091 public:
Niels Möller0694ce72021-05-03 16:03:22 +020092 DEPRECATED_AsyncInvoker();
93 ~DEPRECATED_AsyncInvoker() override;
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +020094
Artem Titov96e3b992021-07-26 16:03:14 +020095 // Call `functor` asynchronously on `thread`, with no callback upon
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +020096 // completion. Returns immediately.
97 template <class ReturnT, class FunctorT>
98 void AsyncInvoke(const Location& posted_from,
99 Thread* thread,
Cameron Pickettd132ce12018-03-12 16:07:37 -0700100 FunctorT&& functor,
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200101 uint32_t id = 0) {
102 std::unique_ptr<AsyncClosure> closure(
Cameron Pickettd132ce12018-03-12 16:07:37 -0700103 new FireAndForgetAsyncClosure<FunctorT>(
104 this, std::forward<FunctorT>(functor)));
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200105 DoInvoke(posted_from, thread, std::move(closure), id);
106 }
107
Artem Titov96e3b992021-07-26 16:03:14 +0200108 // Call `functor` asynchronously on `thread` with `delay_ms`, with no callback
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200109 // upon completion. Returns immediately.
110 template <class ReturnT, class FunctorT>
111 void AsyncInvokeDelayed(const Location& posted_from,
112 Thread* thread,
Cameron Pickettd132ce12018-03-12 16:07:37 -0700113 FunctorT&& functor,
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200114 uint32_t delay_ms,
115 uint32_t id = 0) {
116 std::unique_ptr<AsyncClosure> closure(
Cameron Pickettd132ce12018-03-12 16:07:37 -0700117 new FireAndForgetAsyncClosure<FunctorT>(
118 this, std::forward<FunctorT>(functor)));
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200119 DoInvokeDelayed(posted_from, thread, std::move(closure), delay_ms, id);
120 }
121
Artem Titov96e3b992021-07-26 16:03:14 +0200122 // Synchronously execute on `thread` all outstanding calls we own
123 // that are pending on `thread`, and wait for calls to complete
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200124 // before returning. Optionally filter by message id.
125 // The destructor will not wait for outstanding calls, so if that
126 // behavior is desired, call Flush() before destroying this object.
127 void Flush(Thread* thread, uint32_t id = MQID_ANY);
128
Chris Dziemborowiczc38d3202018-01-31 12:52:24 -0800129 // Cancels any outstanding calls we own that are pending on any thread, and
130 // which have not yet started to execute. This does not wait for any calls
131 // that have already started executing to complete.
132 void Clear();
133
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200134 private:
135 void OnMessage(Message* msg) override;
136 void DoInvoke(const Location& posted_from,
137 Thread* thread,
138 std::unique_ptr<AsyncClosure> closure,
139 uint32_t id);
140 void DoInvokeDelayed(const Location& posted_from,
141 Thread* thread,
142 std::unique_ptr<AsyncClosure> closure,
143 uint32_t delay_ms,
144 uint32_t id);
deadbeef3af63b02017-08-08 17:59:47 -0700145
146 // Used to keep track of how many invocations (AsyncClosures) are still
147 // alive, so that the destructor can wait for them to finish, as described in
148 // the class documentation.
149 //
150 // TODO(deadbeef): Using a raw std::atomic like this is prone to error and
151 // difficult to maintain. We should try to wrap this functionality in a
152 // separate class to reduce the chance of errors being introduced in the
153 // future.
154 std::atomic<int> pending_invocations_;
155
156 // Reference counted so that if the AsyncInvoker destructor finishes before
157 // an AsyncClosure's destructor that's about to call
158 // "invocation_complete_->Set()", it's not dereferenced after being
159 // destroyed.
Tomas Gunnarssone249d192021-04-26 11:46:54 +0200160 rtc::Ref<Event>::Ptr invocation_complete_;
deadbeef3af63b02017-08-08 17:59:47 -0700161
162 // This flag is used to ensure that if an application AsyncInvokes tasks that
163 // recursively AsyncInvoke other tasks ad infinitum, the cycle eventually
164 // terminates.
165 std::atomic<bool> destroying_;
166
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200167 friend class AsyncClosure;
168
Niels Möller0694ce72021-05-03 16:03:22 +0200169 RTC_DISALLOW_COPY_AND_ASSIGN(DEPRECATED_AsyncInvoker);
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200170};
171
Niels Möller0694ce72021-05-03 16:03:22 +0200172using AsyncInvoker ABSL_DEPRECATED("bugs.webrtc.org/12339") =
173 DEPRECATED_AsyncInvoker;
174
Henrik Kjellanderec78f1c2017-06-29 07:52:50 +0200175} // namespace rtc
henrike@webrtc.orgf0488722014-05-13 18:00:26 +0000176
Steve Anton10542f22019-01-11 09:11:00 -0800177#endif // RTC_BASE_ASYNC_INVOKER_H_