From 76d30a507d96f71acada68a79b7da80911aed664 Mon Sep 17 00:00:00 2001
From: Harald Alvestrand <hta@webrtc.org>
Date: Fri, 12 Feb 2021 14:17:59 +0000
Subject: [PATCH] Improve documentation of PendingTaskSafety

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}
---
 .../task_utils/pending_task_safety_flag.h     | 53 +++++++++++++------
 1 file changed, 37 insertions(+), 16 deletions(-)

diff --git a/rtc_base/task_utils/pending_task_safety_flag.h b/rtc_base/task_utils/pending_task_safety_flag.h
index 7e8a470a09..1a805f33e2 100644
--- a/rtc_base/task_utils/pending_task_safety_flag.h
+++ b/rtc_base/task_utils/pending_task_safety_flag.h
@@ -19,16 +19,22 @@
 
 namespace webrtc {
 
-// Use this flag to drop pending tasks that have been posted to the "main"
-// thread/TQ and end up running after the owning instance has been
-// deleted. The owning instance signals deletion by calling SetNotAlive() from
-// its destructor.
-//
+// The PendingTaskSafetyFlag and the ScopedTaskSafety are designed to address
+// the issue where you have a task to be executed later that has references,
+// but cannot guarantee that the referenced object is alive when the task is
+// 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
-// 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|:
 //
-//    // Running outside of the main thread.
+// class ExampleClass {
+// ....
 //    my_task_queue_->PostTask(ToQueuedTask(
 //        [safety = pending_task_safety_flag_, this]() {
 //          // Now running on the main thread.
@@ -36,15 +42,19 @@ namespace webrtc {
 //            return;
 //          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_,
 //        [this]() { MyMethod(); }));
 //
-// Note that checking the state only works on the construction/destruction
-// thread of the ReceiveStatisticsProxy instance.
 class PendingTaskSafetyFlag : public rtc::RefCountInterface {
  public:
   static rtc::scoped_refptr<PendingTaskSafetyFlag> Create();
@@ -62,11 +72,22 @@ class PendingTaskSafetyFlag : public rtc::RefCountInterface {
   RTC_NO_UNIQUE_ADDRESS SequenceChecker main_sequence_;
 };
 
-// Makes using PendingTaskSafetyFlag very simple. Automatic PTSF creation
-// and signalling of destruction when the 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
+// The ScopedTaskSafety makes using PendingTaskSafetyFlag very simple.
+// It does automatic PTSF creation and signalling of destruction when the
+// ScopedTaskSafety instance goes out of scope.
+//
+// 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.
 class ScopedTaskSafety {
  public: