Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 274 insertions, 0 deletions

diff --git a/js/src/builtin/FinalizationRegistryObject.h b/js/src/builtin/FinalizationRegistryObject.h
new file mode 100644
index 0000000000..288ebea424
--- /dev/null
+++ b/js/src/builtin/FinalizationRegistryObject.h
@@ -0,0 +1,274 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ * vim: set ts=8 sts=2 et sw=2 tw=80:
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/*
+ * 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       |     | |  FinalizationObservers   |  |
+ *   |  |  |         weak map          |     | +-------------+------------+  |
+ *   |  |  +---------------------------+     |               |               |
+ *   |  |  | Unregister  :   Records   |     |               v               |
+ *   |  |  |   token     :   object    |     |  +------------+------------+  |
+ *   |  |  +--------------------+------+     |  |      RecordMap map      |  |
+ *   |  |                       |            |  +-------------------------+  |
+ *   |  |                       v            |  |  Target  : Finalization |  |
+ *   |  |  +--------------------+------+     |  |  object  : RecordVector |  |
+ *   |  |  |       Finalization        |     |  +----+-------------+------+  |
+ *   |  |  |    RegistrationsObject    |     |       |             |         |
+ *   |  |  +---------------------------+     |       v             v         |
+ *   |  |  |       RecordVector        |     |  +----+-----+  +----+-----+   |
+ *   |  |  +-------------+-------------+     |  |  Target  |  | (CCW if  |   |
+ *   |  |                |                   |  | JSObject |  |  needed) |   |
+ *   |  |              * 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 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.
+ *
+ * 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.
+ *
+ * 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"
+
+namespace js {
+
+class FinalizationRegistryObject;
+class FinalizationRecordObject;
+class FinalizationQueueObject;
+class ObjectWeakMap;
+
+using HandleFinalizationRegistryObject = Handle<FinalizationRegistryObject*>;
+using HandleFinalizationRecordObject = Handle<FinalizationRecordObject*>;
+using HandleFinalizationQueueObject = Handle<FinalizationQueueObject*>;
+using RootedFinalizationRegistryObject = Rooted<FinalizationRegistryObject*>;
+using RootedFinalizationRecordObject = Rooted<FinalizationRecordObject*>;
+using RootedFinalizationQueueObject = Rooted<FinalizationQueueObject*>;
+
+// A finalization record: a pair of finalization queue and held value.
+//
+// A finalization record represents the registered interest of a finalization
+// registry in a target's finalization.
+//
+// Finalization records created in the 'registered' state but may be
+// unregistered. This happens when:
+//  - the heldValue is passed to the registry's cleanup callback
+//  - the registry's unregister method removes the registration
+//
+// Finalization records are added to a per-zone record map. They are removed
+// when the record is queued for cleanup, or if the interest in finalization is
+// cancelled. See FinalizationObservers::shouldRemoveRecord for the possible
+// reasons.
+
+class FinalizationRecordObject : public NativeObject {
+  enum { QueueSlot = 0, HeldValueSlot, InMapSlot, SlotCount };
+
+ public:
+  static const JSClass class_;
+
+  static FinalizationRecordObject* create(JSContext* cx,
+                                          HandleFinalizationQueueObject queue,
+                                          HandleValue heldValue);
+
+  FinalizationQueueObject* queue() const;
+  Value heldValue() const;
+  bool isRegistered() const;
+  bool isInRecordMap() const;
+
+  void setInRecordMap(bool newValue);
+  void clear();
+};
+
+// A vector of weakly-held FinalizationRecordObjects.
+using WeakFinalizationRecordVector =
+    GCVector<WeakHeapPtr<FinalizationRecordObject*>, 1, js::CellAllocPolicy>;
+
+// A JS object containing a vector of weakly-held FinalizationRecordObjects,
+// which holds the records corresponding to the registrations for a particular
+// registration token. These are used as the values in the registration
+// weakmap. Since the contents of the vector are weak references they are not
+// traced.
+class FinalizationRegistrationsObject : public NativeObject {
+  enum { RecordsSlot = 0, SlotCount };
+
+ public:
+  static const JSClass class_;
+
+  static FinalizationRegistrationsObject* create(JSContext* cx);
+
+  WeakFinalizationRecordVector* records();
+  const WeakFinalizationRecordVector* records() const;
+
+  bool isEmpty() const;
+
+  bool append(HandleFinalizationRecordObject record);
+  void remove(HandleFinalizationRecordObject record);
+
+  bool traceWeak(JSTracer* trc);
+
+ private:
+  static const JSClassOps classOps_;
+
+  void* privatePtr() const;
+
+  static void trace(JSTracer* trc, JSObject* obj);
+  static void finalize(JS::GCContext* gcx, JSObject* obj);
+};
+
+using FinalizationRecordVector =
+    GCVector<HeapPtr<FinalizationRecordObject*>, 1, js::CellAllocPolicy>;
+
+// The JS FinalizationRegistry object itself.
+class FinalizationRegistryObject : public NativeObject {
+  enum { QueueSlot = 0, RegistrationsSlot, SlotCount };
+
+ public:
+  static const JSClass class_;
+  static const JSClass protoClass_;
+
+  FinalizationQueueObject* queue() const;
+  ObjectWeakMap* registrations() const;
+
+  void traceWeak(JSTracer* trc);
+
+  static bool unregisterRecord(FinalizationRecordObject* record);
+
+  static bool cleanupQueuedRecords(JSContext* cx,
+                                   HandleFinalizationRegistryObject registry,
+                                   HandleObject callback = nullptr);
+
+ private:
+  static const JSClassOps classOps_;
+  static const ClassSpec classSpec_;
+  static const JSFunctionSpec methods_[];
+  static const JSPropertySpec properties_[];
+
+  static bool construct(JSContext* cx, unsigned argc, Value* vp);
+  static bool register_(JSContext* cx, unsigned argc, Value* vp);
+  static bool unregister(JSContext* cx, unsigned argc, Value* vp);
+  static bool cleanupSome(JSContext* cx, unsigned argc, Value* vp);
+
+  static bool addRegistration(JSContext* cx,
+                              HandleFinalizationRegistryObject registry,
+                              HandleObject unregisterToken,
+                              HandleFinalizationRecordObject record);
+  static void removeRegistrationOnError(
+      HandleFinalizationRegistryObject registry, HandleObject unregisterToken,
+      HandleFinalizationRecordObject record);
+
+  static bool preserveDOMWrapper(JSContext* cx, HandleObject obj);
+
+  static void trace(JSTracer* trc, JSObject* obj);
+  static void finalize(JS::GCContext* gcx, JSObject* obj);
+};
+
+// Contains information about the cleanup callback and the records queued to
+// be cleaned up. This is not exposed to content JS.
+class FinalizationQueueObject : public NativeObject {
+  enum {
+    CleanupCallbackSlot = 0,
+    IncumbentObjectSlot,
+    RecordsToBeCleanedUpSlot,
+    IsQueuedForCleanupSlot,
+    DoCleanupFunctionSlot,
+    HasRegistrySlot,
+    SlotCount
+  };
+
+  enum DoCleanupFunctionSlots {
+    DoCleanupFunction_QueueSlot = 0,
+  };
+
+ public:
+  static const JSClass class_;
+
+  JSObject* cleanupCallback() const;
+  JSObject* incumbentObject() const;
+  FinalizationRecordVector* recordsToBeCleanedUp() const;
+  bool isQueuedForCleanup() const;
+  JSFunction* doCleanupFunction() const;
+  bool hasRegistry() const;
+
+  void queueRecordToBeCleanedUp(FinalizationRecordObject* record);
+  void setQueuedForCleanup(bool value);
+
+  void setHasRegistry(bool newValue);
+
+  static FinalizationQueueObject* create(JSContext* cx,
+                                         HandleObject cleanupCallback);
+
+  static bool cleanupQueuedRecords(JSContext* cx,
+                                   HandleFinalizationQueueObject registry,
+                                   HandleObject callback = nullptr);
+
+ private:
+  static const JSClassOps classOps_;
+
+  static bool doCleanup(JSContext* cx, unsigned argc, Value* vp);
+
+  static void trace(JSTracer* trc, JSObject* obj);
+  static void finalize(JS::GCContext* gcx, JSObject* obj);
+};
+
+}  // namespace js
+
+#endif /* builtin_FinalizationRegistryObject_h */