Bug 1652962 - Update FinalizationRegistry documentation r=sfink
authorJon Coppeard <jcoppeard@mozilla.com>
Sat, 18 Jul 2020 08:04:29 +0000
changeset 541117 53b5c91f375b8fe622e01330d4051616e02f4942
parent 541116 1f396812eae85fe830cc9f5c54f470e74eafe720
child 541118 6cc4638f8fdae90fb40efdd4a31953790106a3a2
push id37614
push userccoroiu@mozilla.com
push dateSun, 19 Jul 2020 09:04:14 +0000
treeherdermozilla-central@e785ebabf7e1 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerssfink
bugs1652962
milestone80.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1652962 - Update FinalizationRegistry documentation r=sfink Differential Revision: https://phabricator.services.mozilla.com/D83761
js/src/builtin/FinalizationRegistryObject.h
--- a/js/src/builtin/FinalizationRegistryObject.h
+++ b/js/src/builtin/FinalizationRegistryObject.h
@@ -7,76 +7,85 @@
 /*
  * FinalizationRegistry objects allow a program to register to receive a
  * callback after a 'target' object dies. The callback is passed a 'held value'
  * (that hopefully doesn't entrain the target). An 'unregister token' is an
  * object which can be used to remove multiple previous registrations in one go.
  *
  * To arrange this, the following data structures are used:
  *
- *   +-------------------------------------+---------------------------------+
- *   |   FinalizationRegistry compartment  |    Target zone / compartment    |
- *   |                                     |                                 |
- *   |        +----------------------+     |      +------------------+       |
- *   |  +---->+ FinalizationRegistry |     |      |       Zone       |       |
- *   |  |     +---------+------------+     |      +---------+--------+       |
- *   |  |               |                  |                |                |
- *   |  |               v                  |                v                |
- *   |  |  +------------+--------------+   |   +------------+------------+   |
- *   |  |  |       Registrations       |   |   |  FinalizationRecordMap  |   |
- *   |  |  |         weak map          |   |   |           map           |   |
- *   |  |  +---------------------------+   |   +-------------------------+   |
- *   |  |  | Unregister  :   Records   |   |   |  Target  : Finalization-|   |
- *   |  |  |   token     :   object    |   |   |  object  : RecordVector |   |
- *   |  |  +--------------------+------+   |   +----+-------------+------+   |
- *   |  |                       |          |        |             |          |
- *   |  |                       v          |        v             |          |
- *   |  |  +--------------------+------+   |   +----+-----+       |          |
- *   |  |  |       Finalization-       |   |   |  Target  |       |          |
- *   |  |  |    RegistrationsObject    |   |   | JSObject |       |          |
- *   |  |  +-------------+-------------+   |   +----------+       |          |
- *   |  |  |       RecordVector        |   |                      |          |
- *   |  |  +-------------+-------------+   |                      |          |
- *   |  |                |                 |                      |          |
- *   |  |              * v                 |                      |          |
- *   |  |  +-------------+-------------+ * |                      |          |
- *   |  |  | FinalizationRecordObject  +<-------------------------+          |
- *   |  |  +---------------------------+   |                                 |
- *   |  +--+ Registry                  |   |                                 |
- *   |     +---------------------------+   |                                 |
- *   |     | Held value                |   |                                 |
- *   |     +---------------------------+   |                                 |
- *   |                                     |                                 |
- *   +-------------------------------------+---------------------------------+
+ *   +---------------------------------------+-------------------------------+
+ *   |   FinalizationRegistry compartment    |   Target zone / compartment   |
+ *   |                                       |                               |
+ *   |        +----------------------+       |     +------------------+      |
+ *   |  +-----+ FinalizationRegistry |       |     |       Zone       |      |
+ *   |  |     +----------+-----------+       |     +---------+--------+      |
+ *   |  |                |                   |               |               |
+ *   |  |                v                   |               v               |
+ *   |  |  +-------------+-------------+     |  +------------+------------+  |
+ *   |  |  |       Registrations       |     |  |  FinalizationRecordMap  |  |
+ *   |  |  |         weak map          |     |  |           map           |  |
+ *   |  |  +---------------------------+     |  +-------------------------+  |
+ *   |  |  | Unregister  :   Records   |     |  |  Target  : Finalization |  |
+ *   |  |  |   token     :   object    |     |  |  object  : RecordVector |  |
+ *   |  |  +--------------------+------+     |  +----+-------------+------+  |
+ *   |  |                       |            |       |             |         |
+ *   |  |                       v            |       v             |         |
+ *   |  |  +--------------------+------+     |  +----+-----+       |         |
+ *   |  |  |       Finalization        |     |  |  Target  |       |         |
+ *   |  |  |    RegistrationsObject    |     |  | JSObject |       |         |
+ *   |  |  +---------------------------+     |  +----------+       |         |
+ *   |  |  |       RecordVector        |     |                     |         |
+ *   |  |  +-------------+-------------+     |                     |         |
+ *   |  |                |                   |                     |         |
+ *   |  |              * v                   |                     |         |
+ *   |  |  +-------------+-------------+ *   |                     |         |
+ *   |  |  | FinalizationRecordObject  +<--------------------------+         |
+ *   |  |  +---------------------------+     |                               |
+ *   |  |  | Queue                     +--+  |                               |
+ *   |  |  +---------------------------+  |  |                               |
+ *   |  |  | Held value                |  |  |                               |
+ *   |  |  +---------------------------+  |  |                               |
+ *   |  |                                 |  |                               |
+ *   |  +--------------+   +--------------+  |                               |
+ *   |                 |   |                 |                               |
+ *   |                 v   v                 |                               |
+ *   |      +----------+---+----------+      |                               |
+ *   |      | FinalizationQueueObject |      |                               |
+ *   |      +-------------------------+      |                               |
+ *   |                                       |                               |
+ *   +---------------------------------------+-------------------------------+
+ *
+ * A FinalizationRegistry consists of two parts: the FinalizationRegistry that
+ * consumers see and a FinalizationQueue used internally to queue and call the
+ * cleanup callbacks.
  *
  * Registering a target with a FinalizationRegistry creates a FinalizationRecord
- * containing the registry and the heldValue. This is added to a vector of
- * records associated with the target, implemented as a map on the target's
- * Zone. All finalization records are treated as GC roots.
+ * containing a pointer to the queue and the heldValue. This is added to a
+ * vector of records associated with the target, implemented as a map on the
+ * target's Zone. All finalization records are treated as GC roots.
  *
  * When a target is registered an unregister token may be supplied. If so, this
  * is also recorded by the registry and is stored in a weak map of
  * registrations. The values of this map are FinalizationRegistrationsObject
  * objects. It's necessary to have another JSObject here because our weak map
  * implementation only supports JS types as values.
  *
- * After a target object has been registered with a finalization registry it is
- * expected that its callback will be called for that object even if the
- * finalization registry itself is no longer reachable from JS. Thus the values
- * of each zone's finalization record map are treated as roots and marked at the
- * start of GC.
+ * When targets are unregistered, the registration is looked up in the weakmap
+ * and the corresponding records are cleared.
+
+ * The finalization record maps are swept during GC to check for records that
+ * have been cleared by unregistration, for FinalizationRecords that are dead
+ * and for nuked CCWs. In all cases the record is removed and the cleanup
+ * callback is not run.
  *
- * The finalization record maps are also swept during GC to check for any
- * targets that are dying. For such targets the associated record list is
- * processed and for each record the heldValue is queued on finalization
- * registry. At a later time this causes the client's callback to be run.
- *
- * When targets are unregistered, the registration is looked up in the weakmap
- * and the corresponding records are cleared. These are removed from the zone's
- * record map when it is next swept.
+ * Following this the targets are checked to see if they are dying. For such
+ * targets the associated record list is processed and for each record the
+ * heldValue is queued on the FinalizationQueue. At a later time this causes the
+ * client's cleanup callback to be run.
  */
 
 #ifndef builtin_FinalizationRegistryObject_h
 #define builtin_FinalizationRegistryObject_h
 
 #include "gc/Barrier.h"
 #include "js/GCVector.h"
 #include "vm/NativeObject.h"