1 files changed, 24 insertions, 0 deletions

diff --git a/chromium/third_party/blink/renderer/bindings/core/v8/active_script_wrappable.h b/chromium/third_party/blink/renderer/bindings/core/v8/active_script_wrappable.h
index 8b310b8f7b3..fcd8b9f8456 100644
--- a/chromium/third_party/blink/renderer/bindings/core/v8/active_script_wrappable.h
+++ b/chromium/third_party/blink/renderer/bindings/core/v8/active_script_wrappable.h
@@ -12,6 +12,30 @@ namespace blink {
 
 class ScriptWrappable;
 
+// Derived by wrappable objects which need to remain alive due to ongoing
+// asynchronous activity, even if they are not referenced in the JavaScript or
+// Blink heap.
+//
+// A ScriptWrappable ordinarily is held alive only if it has some such
+// reference, usually via a wrapper object held by script. However, some
+// objects, such as XMLHttpRequest, have pending activity that may be visible
+// (e.g. firing event listeners or resolving promises), and so should not be
+// collected, even if no references remain.
+//
+// Such objects should derive from ActiveScriptWrappable<T>, and override
+// ScriptWrappable::HasPendingActivity:
+//   bool HasPendingActivity() const final;
+// which returns true if there may be pending activity which requires the
+// wrappable remain alive.
+//
+// During wrapper tracing, ActiveScriptWrappables which belong to a
+// non-destroyed execution context and have pending activity are treated as
+// roots for the purposes of marking and so will keep themselves and objects
+// they reference alive.
+//
+// Since this pending activity will not keep the wrappable alive after the
+// context is destroyed, it is common for ActiveScriptWrappable objects to also
+// derive from ContextLifecycleObserver to abort the activity at that time.
 template <typename T>
 class ActiveScriptWrappable : public ActiveScriptWrappableBase {
   WTF_MAKE_NONCOPYABLE(ActiveScriptWrappable);