Document registration of Oilpan weak callbacks.

third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md

 # Blink GC API reference
 
 This is a through document for Oilpan API usage.
 If you want to learn the API usage quickly, look at
 [this tutorial](https://docs.google.com/presentation/d/1XPu03ymz8W295mCftEC9KshH9Icxfq81YwIJQzQrvxo/edit#slide=id.p).
 
 [TOC]
 
 ## Header file
 
@@ skipping 317 matching lines @@
 ```
 
 Specifically, if your class needs a tracing method, you need to:
 
 *   Declare a tracing method in your class declaration, using the `DECLARE_TRACE()` macro; and
 *   Define a tracing method in your implementation file, using the `DEFINE_TRACE(ClassName)` macro.
 
 The function implementation must contain:
 
 *   For each on-heap object `m_object` in your class, a tracing call: "```visitor->trace(m_object);```".
+*   If your class has one or more weak references (`WeakMember<T>`), you have the option of
+    registering a *weak callback* for the object. See details below for how.
 *   For each base class of your class `BaseClass` that is a descendant of `GarbageCollected<T>` or
-    `GarbageCollectedMixin`, delegation call to base class: "```BaseClass::trace(visitor);```"
+    `GarbageCollectedMixin`, a delegation call to base class: "```BaseClass::trace(visitor);```"
 
 It is recommended that the delegation call, if any, is put at the end of a tracing method.
 
 If the class does not contain any on-heap object, the tracing method is not needed.
 
 If you want to define your tracing method inline or need to have your tracing method polymorphic, you can use the
 following variants of the tracing macros:
 
 *   "```DECLARE_VIRTUAL_TRACE();```" in a class declaration makes the method ```virtual```. Use
     "```DEFINE_TRACE(ClassName) { ... }```" in the implementation file to define.
@@ skipping 25 matching lines @@
 
 DEFINE_TRACE(C)
 {
     visitor->trace(m_x);
     visitor->trace(m_y); // Weak member needs to be traced.
     visitor->trace(m_z); // Heap collection does, too.
     B::trace(visitor); // Delegate to the parent. In this case it's empty, but this is required.
 }
 ```
 
+Given that the class `C` above contained a `WeakMember<Y>` field, you could alternatively
+register a *weak callback* in the trace method, and have it be invoked after the marking
+phase:
+
+```c++
+
+void C::clearWeakMembers(Visitor* visitor)
+{
+    if (ThreadHeap::isHeapObjectAlive(m_y))
+        return;
+
+    // |m_y| is not referred to by anyone else, clear the weak
+    // reference along with updating state / clearing any other
+    // resources at the same time. None of those operations are
+    // allowed to perform heap allocations:
+    m_y->detach();
+
+    // Note: if the weak callback merely clears the weak reference,
+    // it is much simpler to just |trace| the field rather than
+    // install a custom weak callback.
+    m_y = nullptr;
+}
+
+DEFINE_TRACE(C)
+{
+    visitor->template registerWeakMembers<C, &C::clearWeakMembers>(this);
+    visitor->trace(m_x);
+    visitor->trace(m_z); // Heap collection does, too.
+    B::trace(visitor); // Delegate to the parent. In this case it's empty, but this is required.
+}
+```
+
+Please notice that if the object (of type `C`) is also not reachable, its `trace` method
+will not be invoked and any follow-on weak processing will not be done. Hence, if the
+object must always perform some operation when the weak reference is cleared, that
+needs to (also) happen during finalization.
+
+Weak callbacks have so far seen little use in Blink, but a mechanism that's available.
+
 ## Heap collections