zqz/platform-external-webrtc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation of PendingTaskSafety

Browse Source 
Bug: none
Change-Id: Iff9bf0e1965663581ba34f45f71b9cf23032af7a
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/207164
Reviewed-by: Tommi <tommi@webrtc.org>
Commit-Queue: Harald Alvestrand <hta@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#33250}
This commit is contained in:
Harald Alvestrand
2021-02-12 14:17:59 +00:00
committed by Commit Bot
parent bc1cdef4e8
commit 76d30a507d
1 changed files with 37 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
rtc_base/task_utils/pending_task_safety_flag.h
View File

@ -19,16 +19,22 @@
namespace webrtc { namespace webrtc {
// Use this flag to drop pending tasks that have been posted to the "main" // The PendingTaskSafetyFlag and the ScopedTaskSafety are designed to address
// thread/TQ and end up running after the owning instance has been // the issue where you have a task to be executed later that has references,
// deleted. The owning instance signals deletion by calling SetNotAlive() from // but cannot guarantee that the referenced object is alive when the task is
// its destructor. // executed.
//
// This mechanism can be used with tasks that are created and destroyed
// on a single thread / task queue, and with tasks posted to the same
// thread/task queue, but tasks can be posted from any thread/TQ.
// Typical usage:
// When posting a task, post a copy (capture by-value in a lambda) of the flag // When posting a task, post a copy (capture by-value in a lambda) of the flag
// instance and before performing the work, check the |alive()| state. Abort if // reference and before performing the work, check the |alive()| state. Abort if
// alive() returns |false|: // alive() returns |false|:
// //
// // Running outside of the main thread. // class ExampleClass {
// ....
// my_task_queue_->PostTask(ToQueuedTask( // my_task_queue_->PostTask(ToQueuedTask(
// [safety = pending_task_safety_flag_, this]() { // [safety = pending_task_safety_flag_, this]() {
// // Now running on the main thread. // // Now running on the main thread.
@ -36,15 +42,19 @@ namespace webrtc {
// return; // return;
// MyMethod(); // MyMethod();
// })); // }));
// ....
// ~ExampleClass() {
// pending_task_safety_flag_->SetNotAlive();
// }
// scoped_refptr<PendingTaskSafetyFlag> pending_task_safety_flag_
// = PendingTaskSafetyFlag::Create();
// }
// //
// Or implicitly by letting ToQueuedTask do the checking: // ToQueuedTask has an overload that makes this check automatic:
// //
// // Running outside of the main thread.
// my_task_queue_->PostTask(ToQueuedTask(pending_task_safety_flag_, // my_task_queue_->PostTask(ToQueuedTask(pending_task_safety_flag_,
// [this]() { MyMethod(); })); // [this]() { MyMethod(); }));
// //
// Note that checking the state only works on the construction/destruction
// thread of the ReceiveStatisticsProxy instance.
class PendingTaskSafetyFlag : public rtc::RefCountInterface { class PendingTaskSafetyFlag : public rtc::RefCountInterface {
public: public:
static rtc::scoped_refptr<PendingTaskSafetyFlag> Create(); static rtc::scoped_refptr<PendingTaskSafetyFlag> Create();
@ -62,11 +72,22 @@ class PendingTaskSafetyFlag : public rtc::RefCountInterface {
RTC_NO_UNIQUE_ADDRESS SequenceChecker main_sequence_; RTC_NO_UNIQUE_ADDRESS SequenceChecker main_sequence_;
}; };
// Makes using PendingTaskSafetyFlag very simple. Automatic PTSF creation // The ScopedTaskSafety makes using PendingTaskSafetyFlag very simple.
// and signalling of destruction when the ScopedTaskSafety instance goes out // It does automatic PTSF creation and signalling of destruction when the
// of scope. // ScopedTaskSafety instance goes out of scope.
// Should be used by the class that wants tasks dropped after destruction. //
// Requirements are that the instance be constructed and destructed on // ToQueuedTask has an overload that takes a ScopedTaskSafety too, so there
// is no need to explicitly call the "flag" method.
//
// Example usage:
//
// my_task_queue->PostTask(ToQueuedTask(scoped_task_safety,
// [this]() {
// // task goes here
// }
//
// This should be used by the class that wants tasks dropped after destruction.
// The requirement is that the instance has to be constructed and destructed on
// the same thread as the potentially dropped tasks would be running on. // the same thread as the potentially dropped tasks would be running on.
class ScopedTaskSafety { class ScopedTaskSafety {
public: public: