[v8 gc] Introduce a base class for all objects that can have pending activity

third_party/WebKit/Source/bindings/IDLExtendedAttributes.md

Index: third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
diff --git a/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md b/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
index 46ace8a1985d35dcabcefe6e80535fc8e1567d75..3a56f226679b40caec3a1f4ddc25f6c2f83b0784 100644
--- a/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
+++ b/third_party/WebKit/Source/bindings/IDLExtendedAttributes.md
@@ -130,7 +130,7 @@ Extended attributes on members of an implemented interface work as normal. Howev
 
 ### Inheritance
 
-Extended attributes are generally not inherited: only extended attributes on the interface itself are consulted. However, there are a handful of extended attributes that are inherited (applying them to an ancestor interface applies them to the descendants). These are extended attributes that affect memory management, and currently consists of `[DependentLifetime]`; the up-to-date list is [compute_dependencies.INHERITED_EXTENDED_ATTRIBUTES](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/bindings/scripts/compute_dependencies.py&q=INHERITED_EXTENDED_ATTRIBUTES).
+Extended attributes are generally not inherited: only extended attributes on the interface itself are consulted. However, there are a handful of extended attributes that are inherited (applying them to an ancestor interface applies them to the descendants). These are extended attributes that affect memory management, and currently consists of `[DependentLifetime]` and `[RequiresFinalizer]`; the up-to-date list is [compute_dependencies.INHERITED_EXTENDED_ATTRIBUTES](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/bindings/scripts/compute_dependencies.py&q=INHERITED_EXTENDED_ATTRIBUTES).
 
 ## Standard Web IDL Extended Attributes
 
@@ -868,7 +868,7 @@ interface Bar : Foo { ... };  // inherits [DependentLifetime]
 If a DOM object does not have `[DependentLifetime]`, V8's GC collects the wrapper of the DOM object
 if the wrapper is unreachable on the JS side (i.e., V8's GC assumes that the wrapper should not be
 reachable in the DOM side). Use `[DependentLifetime]` to relax the assumption.
-For example, if the DOM object implements hasPendingActivity(), it must be annotated with
+For example, if the DOM object has `[RequiresFinalizer]` and implements hasPendingActivity(), it must be annotated with
 `[DependentLifetime]`. Otherwise, the wrapper will be collected regardless of the returned value
 of the hasPendingActivity(). DOM objects that are pointed to by `[SetWrapperReferenceFrom]` and
 `[SetWrapperReferenceTo]` must be annotated with `[DependentLifetime]`.
@@ -1196,6 +1196,40 @@ If there is no match, the empty string will be returned. As required by the spec
 
 `[ReflectOnly=<list>]` should be used if the specification for a reflected IDL attribute says it is _"limited to only known values"_.
 
+### [RequiresFinalizer] _(i)_

[haraken, 2016/03/18 08:07:28]

"RequiresFinalizer" sounds a bit confusing, since it implies that the DOM object
needs a finalizer or something. I'd rename it to "ActiveScriptWrappable".

+
+Summary: `[RequiresFinalizer]` indicates that a given DOM object should be kept alive as long as the DOM object has pending activities.
+
+Usage: `[RequiresFinalizer]` can be specified on interfaces, and **is inherited**:
+
+```webidl
+[
+    RequiresFinalizer,
+] interface Foo {
+    ...
+};
+```
+
+If an interface X has `[RequiresFinalizer]` and an interface Y inherits the interface X, then the interface Y will also have `[RequiresFinalizer]`. For example
+
+```webidl
+[
+    RequiresFinalizer,
+] interface Foo {};
+```
+
+interface Bar : Foo {};  // inherits [RequiresFinalizer] from Foo
+If a given DOM object needs to be kept alive as long as the DOM object has pending activitiesi, yoiu need to specify `[RequiresFinalizer]` and `[DependentLifetime]`. For example, `[RequiresFinalizer]` can be used when the DOM object is expecting events ot be raised in the future.

[Marcel Hlopko, 2016/03/18 08:34:40]

typo ot

[Marcel Hlopko, 2016/03/18 08:34:40]

typo activitiesi, yoiu

[jochen (gone - plz use gerrit), 2016/03/18 13:18:01]

done

+
+If you use `[RequiresFinalizer]`, the corresponding Blink class needs to inherit ActiveScriptWrappable. For example, in case of XMLHttpRequest, core/xml/XMLHttpRequest.h would look like this:
+
+```c++
+class XMLHttpRequest : public ActiveScriptWrappable
+{
+    ...;
+}
+```
+
 ### [RuntimeEnabled] _(i, m, a, c)_
 
 Summary: `[RuntimeEnabled]` wraps the generated code with `if (RuntimeEnabledFeatures::FeatureNameEnabled) { ...code... }`.