Adding upstream version 124.0.1.upstream/124.0.1

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

1 files changed, 1361 insertions, 0 deletions

diff --git a/js/public/GCAPI.h b/js/public/GCAPI.h
new file mode 100644
index 0000000000..b0f1325a1e
--- /dev/null
+++ b/js/public/GCAPI.h
@@ -0,0 +1,1361 @@
+/* -*- 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/. */
+
+/*
+ * High-level interface to the JS garbage collector.
+ */
+
+#ifndef js_GCAPI_h
+#define js_GCAPI_h
+
+#include "mozilla/TimeStamp.h"
+#include "mozilla/Vector.h"
+
+#include "js/CharacterEncoding.h"  // JS::UTF8Chars
+#include "js/GCAnnotations.h"
+#include "js/shadow/Zone.h"
+#include "js/SliceBudget.h"
+#include "js/TypeDecls.h"
+#include "js/UniquePtr.h"
+#include "js/Utility.h"
+
+class JS_PUBLIC_API JSTracer;
+
+namespace js {
+namespace gc {
+class GCRuntime;
+}  // namespace gc
+class JS_PUBLIC_API SliceBudget;
+namespace gcstats {
+struct Statistics;
+}  // namespace gcstats
+}  // namespace js
+
+namespace JS {
+
+// Options used when starting a GC.
+enum class GCOptions : uint32_t {
+  // Normal GC invocation.
+  //
+  // Some objects that are unreachable from the program may still be alive after
+  // collection because of internal references
+  Normal = 0,
+
+  // A shrinking GC.
+  //
+  // Try to release as much memory as possible by clearing internal caches,
+  // aggressively discarding JIT code and decommitting unused chunks. This
+  // ensures all unreferenced objects are removed from the system.
+  //
+  // Finally, compact the GC heap.
+  Shrink = 1,
+
+  // A shutdown GC.
+  //
+  // This does more drastic cleanup as part of system shutdown, including:
+  //  - clearing WeakRef kept object sets
+  //  - not marking FinalizationRegistry roots
+  //  - repeating collection if JS::NotifyGCRootsRemoved was called
+  //  - skipping scheduling of various future work that won't be needed
+  //
+  // Note that this assumes that no JS will run after this point!
+  Shutdown = 2
+};
+
+}  // namespace JS
+
+typedef enum JSGCParamKey {
+  /**
+   * Maximum nominal heap before last ditch GC.
+   *
+   * Soft limit on the number of bytes we are allowed to allocate in the GC
+   * heap. Attempts to allocate gcthings over this limit will return null and
+   * subsequently invoke the standard OOM machinery, independent of available
+   * physical memory.
+   *
+   * Pref: javascript.options.mem.max
+   * Default: 0xffffffff
+   */
+  JSGC_MAX_BYTES = 0,
+
+  /**
+   * Maximum size of the generational GC nurseries.
+   *
+   * This will be rounded to the nearest gc::ChunkSize.
+   *
+   * Pref: javascript.options.mem.nursery.max_kb
+   * Default: JS::DefaultNurseryMaxBytes
+   */
+  JSGC_MAX_NURSERY_BYTES = 2,
+
+  /** Amount of bytes allocated by the GC. */
+  JSGC_BYTES = 3,
+
+  /** Number of times GC has been invoked. Includes both major and minor GC. */
+  JSGC_NUMBER = 4,
+
+  /**
+   * Whether incremental GC is enabled. If not, GC will always run to
+   * completion.
+   *
+   * prefs: javascript.options.mem.gc_incremental.
+   * Default: false
+   */
+  JSGC_INCREMENTAL_GC_ENABLED = 5,
+
+  /**
+   * Whether per-zone GC is enabled. If not, all zones are collected every time.
+   *
+   * prefs: javascript.options.mem.gc_per_zone
+   * Default: false
+   */
+  JSGC_PER_ZONE_GC_ENABLED = 6,
+
+  /** Number of cached empty GC chunks. */
+  JSGC_UNUSED_CHUNKS = 7,
+
+  /** Total number of allocated GC chunks. */
+  JSGC_TOTAL_CHUNKS = 8,
+
+  /**
+   * Max milliseconds to spend in an incremental GC slice.
+   *
+   * A value of zero means there is no maximum.
+   *
+   * Pref: javascript.options.mem.gc_incremental_slice_ms
+   * Default: DefaultTimeBudgetMS.
+   */
+  JSGC_SLICE_TIME_BUDGET_MS = 9,
+
+  /**
+   * The "do we collect?" decision depends on various parameters and can be
+   * summarised as:
+   *
+   *   ZoneSize > Max(ThresholdBase, LastSize) * GrowthFactor * ThresholdFactor
+   *
+   * Where
+   *   ZoneSize: Current size of this zone.
+   *   LastSize: Heap size immediately after the most recent collection.
+   *   ThresholdBase: The JSGC_ALLOCATION_THRESHOLD parameter
+   *   GrowthFactor: A number above 1, calculated based on some of the
+   *                 following parameters.
+   *                 See computeZoneHeapGrowthFactorForHeapSize() in GC.cpp
+   *   ThresholdFactor: 1.0 to trigger an incremental collections or between
+   *                    JSGC_SMALL_HEAP_INCREMENTAL_LIMIT and
+   *                    JSGC_LARGE_HEAP_INCREMENTAL_LIMIT to trigger a
+   *                    non-incremental collection.
+   *
+   * The RHS of the equation above is calculated and sets
+   * zone->gcHeapThreshold.bytes(). When gcHeapSize.bytes() exeeds
+   * gcHeapThreshold.bytes() for a zone, the zone may be scheduled for a GC.
+   */
+
+  /**
+   * GCs less than this far apart in milliseconds will be considered
+   * 'high-frequency GCs'.
+   *
+   * Pref: javascript.options.mem.gc_high_frequency_time_limit_ms
+   * Default: HighFrequencyThreshold
+   */
+  JSGC_HIGH_FREQUENCY_TIME_LIMIT = 11,
+
+  /**
+   * Upper limit for classifying a heap as small (MB).
+   *
+   * Dynamic heap growth thresholds are based on whether the heap is small,
+   * medium or large. Heaps smaller than this size are classified as small;
+   * larger heaps are classified as medium or large.
+   *
+   * Pref: javascript.options.mem.gc_small_heap_size_max_mb
+   * Default: SmallHeapSizeMaxBytes
+   */
+  JSGC_SMALL_HEAP_SIZE_MAX = 12,
+
+  /**
+   * Lower limit for classifying a heap as large (MB).
+   *
+   * Dynamic heap growth thresholds are based on whether the heap is small,
+   * medium or large. Heaps larger than this size are classified as large;
+   * smaller heaps are classified as small or medium.
+   *
+   * Pref: javascript.options.mem.gc_large_heap_size_min_mb
+   * Default: LargeHeapSizeMinBytes
+   */
+  JSGC_LARGE_HEAP_SIZE_MIN = 13,
+
+  /**
+   * Heap growth factor for small heaps in the high-frequency GC state.
+   *
+   * Pref: javascript.options.mem.gc_high_frequency_small_heap_growth
+   * Default: HighFrequencySmallHeapGrowth
+   */
+  JSGC_HIGH_FREQUENCY_SMALL_HEAP_GROWTH = 14,
+
+  /**
+   * Heap growth factor for large heaps in the high-frequency GC state.
+   *
+   * Pref: javascript.options.mem.gc_high_frequency_large_heap_growth
+   * Default: HighFrequencyLargeHeapGrowth
+   */
+  JSGC_HIGH_FREQUENCY_LARGE_HEAP_GROWTH = 15,
+
+  /**
+   * Heap growth factor for low frequency GCs.
+   *
+   * This factor is applied regardless of the size of the heap when not in the
+   * high-frequency GC state.
+   *
+   * Pref: javascript.options.mem.gc_low_frequency_heap_growth
+   * Default: LowFrequencyHeapGrowth
+   */
+  JSGC_LOW_FREQUENCY_HEAP_GROWTH = 16,
+
+  /**
+   * Whether balanced heap limits are enabled.
+   *
+   * If this is set to true then heap limits are calculated in a way designed to
+   * balance memory usage optimally between many heaps.
+   *
+   * Otherwise, heap limits are set based on a linear multiple of the retained
+   * size after the last collection.
+   *
+   * Pref: javascript.options.mem.gc_balanced_heap_limits
+   * Default: BalancedHeapLimitsEnabled
+   */
+  JSGC_BALANCED_HEAP_LIMITS_ENABLED = 17,
+
+  /**
+   * Heap growth parameter for balanced heap limit calculation.
+   *
+   * This parameter trades off GC time for memory usage. Smaller values result
+   * in lower memory use and larger values result in less time spent collecting.
+   *
+   * Heap limits are set to the heap's retained size plus some extra space. The
+   * extra space is calculated based on several factors but is scaled
+   * proportionally to this parameter.
+   *
+   * Pref: javascript.options.mem.gc_heap_growth_factor
+   * Default: HeapGrowthFactor
+   */
+  JSGC_HEAP_GROWTH_FACTOR = 18,
+
+  /**
+   * Lower limit for collecting a zone (MB).
+   *
+   * Zones smaller than this size will not normally be collected.
+   *
+   * Pref: javascript.options.mem.gc_allocation_threshold_mb
+   * Default GCZoneAllocThresholdBase
+   */
+  JSGC_ALLOCATION_THRESHOLD = 19,
+
+  /**
+   * We try to keep at least this many unused chunks in the free chunk pool at
+   * all times, even after a shrinking GC.
+   *
+   * Pref: javascript.options.mem.gc_min_empty_chunk_count
+   * Default: MinEmptyChunkCount
+   */
+  JSGC_MIN_EMPTY_CHUNK_COUNT = 21,
+
+  /**
+   * We never keep more than this many unused chunks in the free chunk pool.
+   *
+   * Pref: javascript.options.mem.gc_max_empty_chunk_count
+   * Default: MaxEmptyChunkCount
+   */
+  JSGC_MAX_EMPTY_CHUNK_COUNT = 22,
+
+  /**
+   * Whether compacting GC is enabled.
+   *
+   * Pref: javascript.options.mem.gc_compacting
+   * Default: CompactingEnabled
+   */
+  JSGC_COMPACTING_ENABLED = 23,
+
+  /**
+   * Whether parallel marking is enabled.
+   *
+   * Pref: javascript.options.mem.gc_parallel_marking
+   * Default: ParallelMarkingEnabled
+   */
+  JSGC_PARALLEL_MARKING_ENABLED = 24,
+
+  /**
+   * Limit of how far over the incremental trigger threshold we allow the heap
+   * to grow before finishing a collection non-incrementally, for small heaps.
+   *
+   * We trigger an incremental GC when a trigger threshold is reached but the
+   * collection may not be fast enough to keep up with the mutator. At some
+   * point we finish the collection non-incrementally.
+   *
+   * Default: SmallHeapIncrementalLimit
+   * Pref: javascript.options.mem.gc_small_heap_incremental_limit
+   */
+  JSGC_SMALL_HEAP_INCREMENTAL_LIMIT = 25,
+
+  /**
+   * Limit of how far over the incremental trigger threshold we allow the heap
+   * to grow before finishing a collection non-incrementally, for large heaps.
+   *
+   * Default: LargeHeapIncrementalLimit
+   * Pref: javascript.options.mem.gc_large_heap_incremental_limit
+   */
+  JSGC_LARGE_HEAP_INCREMENTAL_LIMIT = 26,
+
+  /**
+   * Attempt to run a minor GC in the idle time if the free space falls
+   * below this number of bytes.
+   *
+   * Default: NurseryChunkUsableSize / 4
+   * Pref: None
+   */
+  JSGC_NURSERY_FREE_THRESHOLD_FOR_IDLE_COLLECTION = 27,
+
+  /**
+   * Attempt to run a minor GC in the idle time if the free space falls
+   * below this percentage (from 0 to 99).
+   *
+   * Default: 25
+   * Pref: None
+   */
+  JSGC_NURSERY_FREE_THRESHOLD_FOR_IDLE_COLLECTION_PERCENT = 30,
+
+  /**
+   * Minimum size of the generational GC nurseries.
+   *
+   * This value will be rounded to the nearest Nursery::SubChunkStep if below
+   * gc::ChunkSize, otherwise it'll be rounded to the nearest gc::ChunkSize.
+   *
+   * Default: Nursery::SubChunkLimit
+   * Pref: javascript.options.mem.nursery.min_kb
+   */
+  JSGC_MIN_NURSERY_BYTES = 31,
+
+  /**
+   * The minimum time to allow between triggering last ditch GCs in seconds.
+   *
+   * Default: 60 seconds
+   * Pref: None
+   */
+  JSGC_MIN_LAST_DITCH_GC_PERIOD = 32,
+
+  /**
+   * The delay (in heapsize kilobytes) between slices of an incremental GC.
+   *
+   * Default: ZoneAllocDelayBytes
+   */
+  JSGC_ZONE_ALLOC_DELAY_KB = 33,
+
+  /*
+   * The current size of the nursery.
+   *
+   * This parameter is read-only.
+   */
+  JSGC_NURSERY_BYTES = 34,
+
+  /**
+   * Retained size base value for calculating malloc heap threshold.
+   *
+   * Default: MallocThresholdBase
+   */
+  JSGC_MALLOC_THRESHOLD_BASE = 35,
+
+  /**
+   * Whether incremental weakmap marking is enabled.
+   *
+   * Pref: javascript.options.mem.incremental_weakmap
+   * Default: IncrementalWeakMarkEnabled
+   */
+  JSGC_INCREMENTAL_WEAKMAP_ENABLED = 37,
+
+  /**
+   * The chunk size in bytes for this system.
+   *
+   * This parameter is read-only.
+   */
+  JSGC_CHUNK_BYTES = 38,
+
+  /**
+   * The number of background threads to use for parallel GC work for each CPU
+   * core, expressed as an integer percentage.
+   *
+   * Pref: javascript.options.mem.gc_helper_thread_ratio
+   */
+  JSGC_HELPER_THREAD_RATIO = 39,
+
+  /**
+   * The maximum number of background threads to use for parallel GC work.
+   *
+   * Pref: javascript.options.mem.gc_max_helper_threads
+   */
+  JSGC_MAX_HELPER_THREADS = 40,
+
+  /**
+   * The number of background threads to use for parallel GC work.
+   *
+   * This parameter is read-only and is set based on the
+   * JSGC_HELPER_THREAD_RATIO and JSGC_MAX_HELPER_THREADS parameters.
+   */
+  JSGC_HELPER_THREAD_COUNT = 41,
+
+  /**
+   * A number that is incremented on every major GC slice.
+   */
+  JSGC_MAJOR_GC_NUMBER = 44,
+
+  /**
+   * A number that is incremented on every minor GC.
+   */
+  JSGC_MINOR_GC_NUMBER = 45,
+
+  /**
+   * JS::MaybeRunNurseryCollection will collect the nursery if it hasn't been
+   * collected in this many milliseconds.
+   *
+   * Default: 5000
+   * Pref: None
+   */
+  JSGC_NURSERY_TIMEOUT_FOR_IDLE_COLLECTION_MS = 46,
+
+  /**
+   * The system page size in KB.
+   *
+   * This parameter is read-only.
+   */
+  JSGC_SYSTEM_PAGE_SIZE_KB = 47,
+
+  /**
+   * In an incremental GC, this determines the point at which to start
+   * increasing the slice budget and frequency of allocation triggered slices to
+   * try to avoid reaching the incremental limit and finishing the collection
+   * synchronously.
+   *
+   * The threshold is calculated by subtracting this value from the heap's
+   * incremental limit.
+   */
+  JSGC_URGENT_THRESHOLD_MB = 48,
+
+  /**
+   * Set the number of threads to use for parallel marking, or zero to use the
+   * default.
+   *
+   * The actual number used is capped to the number of available helper threads.
+   *
+   * This is provided for testing purposes.
+   *
+   * Pref: None.
+   * Default: 0 (no effect).
+   */
+  JSGC_MARKING_THREAD_COUNT = 49,
+
+  /**
+   * The heap size above which to use parallel marking.
+   *
+   * Default: ParallelMarkingThresholdMB
+   */
+  JSGC_PARALLEL_MARKING_THRESHOLD_MB = 50,
+} JSGCParamKey;
+
+/*
+ * Generic trace operation that calls JS::TraceEdge on each traceable thing's
+ * location reachable from data.
+ */
+typedef void (*JSTraceDataOp)(JSTracer* trc, void* data);
+
+/*
+ * Trace hook used to trace gray roots incrementally.
+ *
+ * This should return whether tracing is finished. It will be called repeatedly
+ * in subsequent GC slices until it returns true.
+ *
+ * While tracing this should check the budget and return false if it has been
+ * exceeded. When passed an unlimited budget it should always return true.
+ */
+typedef bool (*JSGrayRootsTracer)(JSTracer* trc, js::SliceBudget& budget,
+                                  void* data);
+
+typedef enum JSGCStatus { JSGC_BEGIN, JSGC_END } JSGCStatus;
+
+typedef void (*JSObjectsTenuredCallback)(JSContext* cx, void* data);
+
+typedef enum JSFinalizeStatus {
+  /**
+   * Called when preparing to sweep a group of zones, before anything has been
+   * swept.  The collector will not yield to the mutator before calling the
+   * callback with JSFINALIZE_GROUP_START status.
+   */
+  JSFINALIZE_GROUP_PREPARE,
+
+  /**
+   * Called after preparing to sweep a group of zones. Weak references to
+   * unmarked things have been removed at this point, but no GC things have
+   * been swept. The collector may yield to the mutator after this point.
+   */
+  JSFINALIZE_GROUP_START,
+
+  /**
+   * Called after sweeping a group of zones. All dead GC things have been
+   * swept at this point.
+   */
+  JSFINALIZE_GROUP_END,
+
+  /**
+   * Called at the end of collection when everything has been swept.
+   */
+  JSFINALIZE_COLLECTION_END
+} JSFinalizeStatus;
+
+typedef void (*JSFinalizeCallback)(JS::GCContext* gcx, JSFinalizeStatus status,
+                                   void* data);
+
+typedef void (*JSWeakPointerZonesCallback)(JSTracer* trc, void* data);
+
+typedef void (*JSWeakPointerCompartmentCallback)(JSTracer* trc,
+                                                 JS::Compartment* comp,
+                                                 void* data);
+
+/*
+ * This is called to tell the embedding that a FinalizationRegistry object has
+ * cleanup work, and that the engine should be called back at an appropriate
+ * later time to perform this cleanup, by calling the function |doCleanup|.
+ *
+ * This callback must not do anything that could cause GC.
+ */
+using JSHostCleanupFinalizationRegistryCallback =
+    void (*)(JSFunction* doCleanup, JSObject* incumbentGlobal, void* data);
+
+/**
+ * Each external string has a pointer to JSExternalStringCallbacks. Embedders
+ * can use this to implement custom finalization or memory reporting behavior.
+ */
+struct JSExternalStringCallbacks {
+  /**
+   * Finalizes external strings created by JS_NewExternalStringLatin1 or
+   * JS_NewExternalUCString. The finalizer can be called off the main
+   * thread.
+   */
+  virtual void finalize(JS::Latin1Char* chars) const = 0;
+  virtual void finalize(char16_t* chars) const = 0;
+
+  /**
+   * Callback used by memory reporting to ask the embedder how much memory an
+   * external string is keeping alive.  The embedder is expected to return a
+   * value that corresponds to the size of the allocation that will be released
+   * by the finalizer callback above.
+   *
+   * Implementations of this callback MUST NOT do anything that can cause GC.
+   */
+  virtual size_t sizeOfBuffer(const JS::Latin1Char* chars,
+                              mozilla::MallocSizeOf mallocSizeOf) const = 0;
+  virtual size_t sizeOfBuffer(const char16_t* chars,
+                              mozilla::MallocSizeOf mallocSizeOf) const = 0;
+};
+
+namespace JS {
+
+#define GCREASONS(D)                                                   \
+  /* Reasons internal to the JS engine. */                             \
+  D(API, 0)                                                            \
+  D(EAGER_ALLOC_TRIGGER, 1)                                            \
+  D(DESTROY_RUNTIME, 2)                                                \
+  D(ROOTS_REMOVED, 3)                                                  \
+  D(LAST_DITCH, 4)                                                     \
+  D(TOO_MUCH_MALLOC, 5)                                                \
+  D(ALLOC_TRIGGER, 6)                                                  \
+  D(DEBUG_GC, 7)                                                       \
+  D(COMPARTMENT_REVIVED, 8)                                            \
+  D(RESET, 9)                                                          \
+  D(OUT_OF_NURSERY, 10)                                                \
+  D(EVICT_NURSERY, 11)                                                 \
+  D(SHARED_MEMORY_LIMIT, 13)                                           \
+  D(EAGER_NURSERY_COLLECTION, 14)                                      \
+  D(BG_TASK_FINISHED, 15)                                              \
+  D(ABORT_GC, 16)                                                      \
+  D(FULL_WHOLE_CELL_BUFFER, 17)                                        \
+  D(FULL_GENERIC_BUFFER, 18)                                           \
+  D(FULL_VALUE_BUFFER, 19)                                             \
+  D(FULL_CELL_PTR_OBJ_BUFFER, 20)                                      \
+  D(FULL_SLOT_BUFFER, 21)                                              \
+  D(FULL_SHAPE_BUFFER, 22)                                             \
+  D(TOO_MUCH_WASM_MEMORY, 23)                                          \
+  D(DISABLE_GENERATIONAL_GC, 24)                                       \
+  D(FINISH_GC, 25)                                                     \
+  D(PREPARE_FOR_TRACING, 26)                                           \
+  D(FULL_WASM_ANYREF_BUFFER, 27)                                       \
+  D(FULL_CELL_PTR_STR_BUFFER, 28)                                      \
+  D(TOO_MUCH_JIT_CODE, 29)                                             \
+  D(FULL_CELL_PTR_BIGINT_BUFFER, 30)                                   \
+  D(NURSERY_TRAILERS, 31)                                              \
+  D(NURSERY_MALLOC_BUFFERS, 32)                                        \
+                                                                       \
+  /*                                                                   \
+   * Reasons from Firefox.                                             \
+   *                                                                   \
+   * The JS engine attaches special meanings to some of these reasons. \
+   */                                                                  \
+  D(DOM_WINDOW_UTILS, FIRST_FIREFOX_REASON)                            \
+  D(COMPONENT_UTILS, 34)                                               \
+  D(MEM_PRESSURE, 35)                                                  \
+  D(CC_FINISHED, 36)                                                   \
+  D(CC_FORCED, 37)                                                     \
+  D(LOAD_END, 38)                                                      \
+  D(UNUSED3, 39)                                                       \
+  D(PAGE_HIDE, 40)                                                     \
+  D(NSJSCONTEXT_DESTROY, 41)                                           \
+  D(WORKER_SHUTDOWN, 42)                                               \
+  D(SET_DOC_SHELL, 43)                                                 \
+  D(DOM_UTILS, 44)                                                     \
+  D(DOM_IPC, 45)                                                       \
+  D(DOM_WORKER, 46)                                                    \
+  D(INTER_SLICE_GC, 47)                                                \
+  D(UNUSED1, 48)                                                       \
+  D(FULL_GC_TIMER, 49)                                                 \
+  D(SHUTDOWN_CC, 50)                                                   \
+  D(UNUSED2, 51)                                                       \
+  D(USER_INACTIVE, 52)                                                 \
+  D(XPCONNECT_SHUTDOWN, 53)                                            \
+  D(DOCSHELL, 54)                                                      \
+  D(HTML_PARSER, 55)                                                   \
+  D(DOM_TESTUTILS, 56)                                                 \
+  D(PREPARE_FOR_PAGELOAD, 57)                                          \
+                                                                       \
+  /* Reasons reserved for embeddings. */                               \
+  D(RESERVED1, FIRST_RESERVED_REASON)                                  \
+  D(RESERVED2, 91)                                                     \
+  D(RESERVED3, 92)                                                     \
+  D(RESERVED4, 93)                                                     \
+  D(RESERVED5, 94)                                                     \
+  D(RESERVED6, 95)                                                     \
+  D(RESERVED7, 96)                                                     \
+  D(RESERVED8, 97)                                                     \
+  D(RESERVED9, 98)
+
+enum class GCReason {
+  FIRST_FIREFOX_REASON = 33,
+  FIRST_RESERVED_REASON = 90,
+
+#define MAKE_REASON(name, val) name = val,
+  GCREASONS(MAKE_REASON)
+#undef MAKE_REASON
+      NO_REASON,
+  NUM_REASONS,
+
+  /*
+   * For telemetry, we want to keep a fixed max bucket size over time so we
+   * don't have to switch histograms. 100 is conservative; but the cost of extra
+   * buckets seems to be low while the cost of switching histograms is high.
+   */
+  NUM_TELEMETRY_REASONS = 100
+};
+
+/**
+ * Get a statically allocated C string explaining the given GC reason.
+ */
+extern JS_PUBLIC_API const char* ExplainGCReason(JS::GCReason reason);
+
+/**
+ * Return true if the GC reason is internal to the JS engine.
+ */
+extern JS_PUBLIC_API bool InternalGCReason(JS::GCReason reason);
+
+/*
+ * Zone GC:
+ *
+ * SpiderMonkey's GC is capable of performing a collection on an arbitrary
+ * subset of the zones in the system. This allows an embedding to minimize
+ * collection time by only collecting zones that have run code recently,
+ * ignoring the parts of the heap that are unlikely to have changed.
+ *
+ * When triggering a GC using one of the functions below, it is first necessary
+ * to select the zones to be collected. To do this, you can call
+ * PrepareZoneForGC on each zone, or you can call PrepareForFullGC to select
+ * all zones. Failing to select any zone is an error.
+ */
+
+/**
+ * Schedule the given zone to be collected as part of the next GC.
+ */
+extern JS_PUBLIC_API void PrepareZoneForGC(JSContext* cx, Zone* zone);
+
+/**
+ * Schedule all zones to be collected in the next GC.
+ */
+extern JS_PUBLIC_API void PrepareForFullGC(JSContext* cx);
+
+/**
+ * When performing an incremental GC, the zones that were selected for the
+ * previous incremental slice must be selected in subsequent slices as well.
+ * This function selects those slices automatically.
+ */
+extern JS_PUBLIC_API void PrepareForIncrementalGC(JSContext* cx);
+
+/**
+ * Returns true if any zone in the system has been scheduled for GC with one of
+ * the functions above or by the JS engine.
+ */
+extern JS_PUBLIC_API bool IsGCScheduled(JSContext* cx);
+
+/**
+ * Undoes the effect of the Prepare methods above. The given zone will not be
+ * collected in the next GC.
+ */
+extern JS_PUBLIC_API void SkipZoneForGC(JSContext* cx, Zone* zone);
+
+/*
+ * Non-Incremental GC:
+ *
+ * The following functions perform a non-incremental GC.
+ */
+
+/**
+ * Performs a non-incremental collection of all selected zones.
+ */
+extern JS_PUBLIC_API void NonIncrementalGC(JSContext* cx, JS::GCOptions options,
+                                           GCReason reason);
+
+/*
+ * Incremental GC:
+ *
+ * Incremental GC divides the full mark-and-sweep collection into multiple
+ * slices, allowing client JavaScript code to run between each slice. This
+ * allows interactive apps to avoid long collection pauses. Incremental GC does
+ * not make collection take less time, it merely spreads that time out so that
+ * the pauses are less noticable.
+ *
+ * For a collection to be carried out incrementally the following conditions
+ * must be met:
+ *  - The collection must be run by calling JS::IncrementalGC() rather than
+ *    JS_GC().
+ *  - The GC parameter JSGC_INCREMENTAL_GC_ENABLED must be true.
+ *
+ * Note: Even if incremental GC is enabled and working correctly,
+ *       non-incremental collections can still happen when low on memory.
+ */
+
+/**
+ * Begin an incremental collection and perform one slice worth of work. When
+ * this function returns, the collection may not be complete.
+ * IncrementalGCSlice() must be called repeatedly until
+ * !IsIncrementalGCInProgress(cx).
+ *
+ * Note: SpiderMonkey's GC is not realtime. Slices in practice may be longer or
+ *       shorter than the requested interval.
+ */
+extern JS_PUBLIC_API void StartIncrementalGC(JSContext* cx,
+                                             JS::GCOptions options,
+                                             GCReason reason,
+                                             const js::SliceBudget& budget);
+
+/**
+ * Perform a slice of an ongoing incremental collection. When this function
+ * returns, the collection may not be complete. It must be called repeatedly
+ * until !IsIncrementalGCInProgress(cx).
+ *
+ * Note: SpiderMonkey's GC is not realtime. Slices in practice may be longer or
+ *       shorter than the requested interval.
+ */
+extern JS_PUBLIC_API void IncrementalGCSlice(JSContext* cx, GCReason reason,
+                                             const js::SliceBudget& budget);
+
+/**
+ * Return whether an incremental GC has work to do on the foreground thread and
+ * would make progress if a slice was run now. If this returns false then the GC
+ * is waiting for background threads to finish their work and a slice started
+ * now would return immediately.
+ */
+extern JS_PUBLIC_API bool IncrementalGCHasForegroundWork(JSContext* cx);
+
+/**
+ * If IsIncrementalGCInProgress(cx), this call finishes the ongoing collection
+ * by performing an arbitrarily long slice. If !IsIncrementalGCInProgress(cx),
+ * this is equivalent to NonIncrementalGC. When this function returns,
+ * IsIncrementalGCInProgress(cx) will always be false.
+ */
+extern JS_PUBLIC_API void FinishIncrementalGC(JSContext* cx, GCReason reason);
+
+/**
+ * If IsIncrementalGCInProgress(cx), this call aborts the ongoing collection and
+ * performs whatever work needs to be done to return the collector to its idle
+ * state. This may take an arbitrarily long time. When this function returns,
+ * IsIncrementalGCInProgress(cx) will always be false.
+ */
+extern JS_PUBLIC_API void AbortIncrementalGC(JSContext* cx);
+
+namespace dbg {
+
+// The `JS::dbg::GarbageCollectionEvent` class is essentially a view of the
+// `js::gcstats::Statistics` data without the uber implementation-specific bits.
+// It should generally be palatable for web developers.
+class GarbageCollectionEvent {
+  // The major GC number of the GC cycle this data pertains to.
+  uint64_t majorGCNumber_;
+
+  // Reference to a non-owned, statically allocated C string. This is a very
+  // short reason explaining why a GC was triggered.
+  const char* reason;
+
+  // Reference to a nullable, non-owned, statically allocated C string. If the
+  // collection was forced to be non-incremental, this is a short reason of
+  // why the GC could not perform an incremental collection.
+  const char* nonincrementalReason;
+
+  // Represents a single slice of a possibly multi-slice incremental garbage
+  // collection.
+  struct Collection {
+    mozilla::TimeStamp startTimestamp;
+    mozilla::TimeStamp endTimestamp;
+  };
+
+  // The set of garbage collection slices that made up this GC cycle.
+  mozilla::Vector<Collection> collections;
+
+  GarbageCollectionEvent(const GarbageCollectionEvent& rhs) = delete;
+  GarbageCollectionEvent& operator=(const GarbageCollectionEvent& rhs) = delete;
+
+ public:
+  explicit GarbageCollectionEvent(uint64_t majorGCNum)
+      : majorGCNumber_(majorGCNum),
+        reason(nullptr),
+        nonincrementalReason(nullptr),
+        collections() {}
+
+  using Ptr = js::UniquePtr<GarbageCollectionEvent>;
+  static Ptr Create(JSRuntime* rt, ::js::gcstats::Statistics& stats,
+                    uint64_t majorGCNumber);
+
+  JSObject* toJSObject(JSContext* cx) const;
+
+  uint64_t majorGCNumber() const { return majorGCNumber_; }
+};
+
+}  // namespace dbg
+
+enum GCProgress {
+  /*
+   * During GC, the GC is bracketed by GC_CYCLE_BEGIN/END callbacks. Each
+   * slice between those (whether an incremental or the sole non-incremental
+   * slice) is bracketed by GC_SLICE_BEGIN/GC_SLICE_END.
+   */
+
+  GC_CYCLE_BEGIN,
+  GC_SLICE_BEGIN,
+  GC_SLICE_END,
+  GC_CYCLE_END
+};
+
+struct JS_PUBLIC_API GCDescription {
+  bool isZone_;
+  bool isComplete_;
+  JS::GCOptions options_;
+  GCReason reason_;
+
+  GCDescription(bool isZone, bool isComplete, JS::GCOptions options,
+                GCReason reason)
+      : isZone_(isZone),
+        isComplete_(isComplete),
+        options_(options),
+        reason_(reason) {}
+
+  char16_t* formatSliceMessage(JSContext* cx) const;
+  char16_t* formatSummaryMessage(JSContext* cx) const;
+
+  mozilla::TimeStamp startTime(JSContext* cx) const;
+  mozilla::TimeStamp endTime(JSContext* cx) const;
+  mozilla::TimeStamp lastSliceStart(JSContext* cx) const;
+  mozilla::TimeStamp lastSliceEnd(JSContext* cx) const;
+
+  JS::UniqueChars sliceToJSONProfiler(JSContext* cx) const;
+  JS::UniqueChars formatJSONProfiler(JSContext* cx) const;
+
+  JS::dbg::GarbageCollectionEvent::Ptr toGCEvent(JSContext* cx) const;
+};
+
+extern JS_PUBLIC_API UniqueChars MinorGcToJSON(JSContext* cx);
+
+typedef void (*GCSliceCallback)(JSContext* cx, GCProgress progress,
+                                const GCDescription& desc);
+
+/**
+ * The GC slice callback is called at the beginning and end of each slice. This
+ * callback may be used for GC notifications as well as to perform additional
+ * marking.
+ */
+extern JS_PUBLIC_API GCSliceCallback
+SetGCSliceCallback(JSContext* cx, GCSliceCallback callback);
+
+/**
+ * Describes the progress of an observed nursery collection.
+ */
+enum class GCNurseryProgress {
+  /**
+   * The nursery collection is starting.
+   */
+  GC_NURSERY_COLLECTION_START,
+  /**
+   * The nursery collection is ending.
+   */
+  GC_NURSERY_COLLECTION_END
+};
+
+/**
+ * A nursery collection callback receives the progress of the nursery collection
+ * and the reason for the collection.
+ */
+using GCNurseryCollectionCallback = void (*)(JSContext* cx,
+                                             GCNurseryProgress progress,
+                                             GCReason reason, void* data);
+
+/**
+ * Add and remove nursery collection callbacks for the given runtime. These will
+ * be called at the start and end of every nursery collection.
+ */
+extern JS_PUBLIC_API bool AddGCNurseryCollectionCallback(
+    JSContext* cx, GCNurseryCollectionCallback callback, void* data);
+extern JS_PUBLIC_API void RemoveGCNurseryCollectionCallback(
+    JSContext* cx, GCNurseryCollectionCallback callback, void* data);
+
+typedef void (*DoCycleCollectionCallback)(JSContext* cx);
+
+/**
+ * The purge gray callback is called after any COMPARTMENT_REVIVED GC in which
+ * the majority of compartments have been marked gray.
+ */
+extern JS_PUBLIC_API DoCycleCollectionCallback
+SetDoCycleCollectionCallback(JSContext* cx, DoCycleCollectionCallback callback);
+
+using CreateSliceBudgetCallback = js::SliceBudget (*)(JS::GCReason reason,
+                                                      int64_t millis);
+
+/**
+ * Called when generating a GC slice budget. It allows the embedding to control
+ * the duration of slices and potentially check an interrupt flag as well. For
+ * internally triggered GCs, the given millis parameter is the JS engine's
+ * internal scheduling decision, which the embedding can choose to ignore.
+ * (Otherwise, it will be the value that was passed to eg
+ * JS::IncrementalGCSlice()).
+ */
+extern JS_PUBLIC_API void SetCreateGCSliceBudgetCallback(
+    JSContext* cx, CreateSliceBudgetCallback cb);
+
+/**
+ * Incremental GC defaults to enabled, but may be disabled for testing or in
+ * embeddings that have not yet implemented barriers on their native classes.
+ * There is not currently a way to re-enable incremental GC once it has been
+ * disabled on the runtime.
+ */
+extern JS_PUBLIC_API void DisableIncrementalGC(JSContext* cx);
+
+/**
+ * Returns true if incremental GC is enabled. Simply having incremental GC
+ * enabled is not sufficient to ensure incremental collections are happening.
+ * See the comment "Incremental GC" above for reasons why incremental GC may be
+ * suppressed. Inspection of the "nonincremental reason" field of the
+ * GCDescription returned by GCSliceCallback may help narrow down the cause if
+ * collections are not happening incrementally when expected.
+ */
+extern JS_PUBLIC_API bool IsIncrementalGCEnabled(JSContext* cx);
+
+/**
+ * Returns true while an incremental GC is ongoing, both when actively
+ * collecting and between slices.
+ */
+extern JS_PUBLIC_API bool IsIncrementalGCInProgress(JSContext* cx);
+
+/**
+ * Returns true while an incremental GC is ongoing, both when actively
+ * collecting and between slices.
+ */
+extern JS_PUBLIC_API bool IsIncrementalGCInProgress(JSRuntime* rt);
+
+/**
+ * Returns true if the most recent GC ran incrementally.
+ */
+extern JS_PUBLIC_API bool WasIncrementalGC(JSRuntime* rt);
+
+/*
+ * Generational GC:
+ */
+
+/**
+ * Ensure that generational GC is disabled within some scope.
+ *
+ * This evicts the nursery and discards JIT code so it is not a lightweight
+ * operation.
+ */
+class JS_PUBLIC_API AutoDisableGenerationalGC {
+  JSContext* cx;
+
+ public:
+  explicit AutoDisableGenerationalGC(JSContext* cx);
+  ~AutoDisableGenerationalGC();
+};
+
+/**
+ * Returns true if generational allocation and collection is currently enabled
+ * on the given runtime.
+ */
+extern JS_PUBLIC_API bool IsGenerationalGCEnabled(JSRuntime* rt);
+
+/**
+ * Pass a subclass of this "abstract" class to callees to require that they
+ * never GC. Subclasses can use assertions or the hazard analysis to ensure no
+ * GC happens.
+ */
+class JS_PUBLIC_API AutoRequireNoGC {
+ protected:
+  AutoRequireNoGC() = default;
+  ~AutoRequireNoGC() = default;
+};
+
+/**
+ * Diagnostic assert (see MOZ_DIAGNOSTIC_ASSERT) that GC cannot occur while this
+ * class is live. This class does not disable the static rooting hazard
+ * analysis.
+ *
+ * This works by entering a GC unsafe region, which is checked on allocation and
+ * on GC.
+ */
+class JS_PUBLIC_API AutoAssertNoGC : public AutoRequireNoGC {
+#ifdef MOZ_DIAGNOSTIC_ASSERT_ENABLED
+ protected:
+  JSContext* cx_;  // nullptr if inactive.
+
+ public:
+  // Nullptr here means get the context from TLS. It does not mean inactive
+  // (though cx_ may end up nullptr, and thus inactive, if TLS has not yet been
+  // initialized.)
+  explicit AutoAssertNoGC(JSContext* cx = nullptr);
+  AutoAssertNoGC(AutoAssertNoGC&& other) : cx_(other.cx_) {
+    other.cx_ = nullptr;
+  }
+  ~AutoAssertNoGC();
+
+  void reset();
+#else
+ public:
+  explicit AutoAssertNoGC(JSContext* cx = nullptr) {}
+  ~AutoAssertNoGC() {}
+
+  void reset() {}
+#endif
+};
+
+/**
+ * Disable the static rooting hazard analysis in the live region and assert in
+ * debug builds if any allocation that could potentially trigger a GC occurs
+ * while this guard object is live. This is most useful to help the exact
+ * rooting hazard analysis in complex regions, since it cannot understand
+ * dataflow.
+ *
+ * Note: GC behavior is unpredictable even when deterministic and is generally
+ *       non-deterministic in practice. The fact that this guard has not
+ *       asserted is not a guarantee that a GC cannot happen in the guarded
+ *       region. As a rule, anyone performing a GC unsafe action should
+ *       understand the GC properties of all code in that region and ensure
+ *       that the hazard analysis is correct for that code, rather than relying
+ *       on this class.
+ */
+#ifdef DEBUG
+class JS_PUBLIC_API AutoSuppressGCAnalysis : public AutoAssertNoGC {
+ public:
+  explicit AutoSuppressGCAnalysis(JSContext* cx = nullptr)
+      : AutoAssertNoGC(cx) {}
+} JS_HAZ_GC_SUPPRESSED;
+#else
+class JS_PUBLIC_API AutoSuppressGCAnalysis : public AutoRequireNoGC {
+ public:
+  explicit AutoSuppressGCAnalysis(JSContext* cx = nullptr) {}
+} JS_HAZ_GC_SUPPRESSED;
+#endif
+
+/**
+ * Assert that code is only ever called from a GC callback, disable the static
+ * rooting hazard analysis and assert if any allocation that could potentially
+ * trigger a GC occurs while this guard object is live.
+ *
+ * This is useful to make the static analysis ignore code that runs in GC
+ * callbacks.
+ */
+class JS_PUBLIC_API AutoAssertGCCallback : public AutoSuppressGCAnalysis {
+ public:
+#ifdef DEBUG
+  AutoAssertGCCallback();
+#else
+  AutoAssertGCCallback() {}
+#endif
+};
+
+/**
+ * Place AutoCheckCannotGC in scopes that you believe can never GC. These
+ * annotations will be verified both dynamically via AutoAssertNoGC, and
+ * statically with the rooting hazard analysis (implemented by making the
+ * analysis consider AutoCheckCannotGC to be a GC pointer, and therefore
+ * complain if it is live across a GC call.) It is useful when dealing with
+ * internal pointers to GC things where the GC thing itself may not be present
+ * for the static analysis: e.g. acquiring inline chars from a JSString* on the
+ * heap.
+ *
+ * We only do the assertion checking in DEBUG builds.
+ */
+#ifdef DEBUG
+class JS_PUBLIC_API AutoCheckCannotGC : public AutoAssertNoGC {
+ public:
+  explicit AutoCheckCannotGC(JSContext* cx = nullptr) : AutoAssertNoGC(cx) {}
+#  ifdef MOZ_DIAGNOSTIC_ASSERT_ENABLED
+  AutoCheckCannotGC(const AutoCheckCannotGC& other)
+      : AutoCheckCannotGC(other.cx_) {}
+#  else
+  AutoCheckCannotGC(const AutoCheckCannotGC& other) : AutoCheckCannotGC() {}
+#  endif
+  AutoCheckCannotGC(AutoCheckCannotGC&& other)
+      : AutoAssertNoGC(std::forward<AutoAssertNoGC>(other)) {}
+#else
+class JS_PUBLIC_API AutoCheckCannotGC : public AutoRequireNoGC {
+ public:
+  explicit AutoCheckCannotGC(JSContext* cx = nullptr) {}
+  AutoCheckCannotGC(const AutoCheckCannotGC& other) : AutoCheckCannotGC() {}
+  AutoCheckCannotGC(AutoCheckCannotGC&& other) : AutoCheckCannotGC() {}
+  void reset() {}
+#endif
+} JS_HAZ_GC_INVALIDATED JS_HAZ_GC_REF;
+
+extern JS_PUBLIC_API void SetLowMemoryState(JSContext* cx, bool newState);
+
+/*
+ * Internal to Firefox.
+ */
+extern JS_PUBLIC_API void NotifyGCRootsRemoved(JSContext* cx);
+
+} /* namespace JS */
+
+typedef void (*JSGCCallback)(JSContext* cx, JSGCStatus status,
+                             JS::GCReason reason, void* data);
+
+/**
+ * Register externally maintained GC roots.
+ *
+ * traceOp: the trace operation. For each root the implementation should call
+ *          JS::TraceEdge whenever the root contains a traceable thing.
+ * data:    the data argument to pass to each invocation of traceOp.
+ */
+extern JS_PUBLIC_API bool JS_AddExtraGCRootsTracer(JSContext* cx,
+                                                   JSTraceDataOp traceOp,
+                                                   void* data);
+
+/** Undo a call to JS_AddExtraGCRootsTracer. */
+extern JS_PUBLIC_API void JS_RemoveExtraGCRootsTracer(JSContext* cx,
+                                                      JSTraceDataOp traceOp,
+                                                      void* data);
+
+extern JS_PUBLIC_API void JS_GC(JSContext* cx,
+                                JS::GCReason reason = JS::GCReason::API);
+
+extern JS_PUBLIC_API void JS_MaybeGC(JSContext* cx);
+
+extern JS_PUBLIC_API void JS_SetGCCallback(JSContext* cx, JSGCCallback cb,
+                                           void* data);
+
+extern JS_PUBLIC_API void JS_SetObjectsTenuredCallback(
+    JSContext* cx, JSObjectsTenuredCallback cb, void* data);
+
+extern JS_PUBLIC_API bool JS_AddFinalizeCallback(JSContext* cx,
+                                                 JSFinalizeCallback cb,
+                                                 void* data);
+
+extern JS_PUBLIC_API void JS_RemoveFinalizeCallback(JSContext* cx,
+                                                    JSFinalizeCallback cb);
+
+/*
+ * Weak pointers and garbage collection
+ *
+ * Weak pointers are by their nature not marked as part of garbage collection,
+ * but they may need to be updated in two cases after a GC:
+ *
+ *  1) Their referent was found not to be live and is about to be finalized
+ *  2) Their referent has been moved by a compacting GC
+ *
+ * To handle this, any part of the system that maintain weak pointers to
+ * JavaScript GC things must register a callback with
+ * JS_(Add,Remove)WeakPointer{ZoneGroup,Compartment}Callback(). This callback
+ * must then call JS_UpdateWeakPointerAfterGC() on all weak pointers it knows
+ * about.
+ *
+ * Since sweeping is incremental, we have several callbacks to avoid repeatedly
+ * having to visit all embedder structures. The WeakPointerZonesCallback is
+ * called once for each strongly connected group of zones, whereas the
+ * WeakPointerCompartmentCallback is called once for each compartment that is
+ * visited while sweeping. Structures that cannot contain references in more
+ * than one compartment should sweep the relevant per-compartment structures
+ * using the latter callback to minimizer per-slice overhead.
+ *
+ * The argument to JS_UpdateWeakPointerAfterGC() is an in-out param. If the
+ * referent is about to be finalized the pointer will be set to null. If the
+ * referent has been moved then the pointer will be updated to point to the new
+ * location.
+ *
+ * The return value of JS_UpdateWeakPointerAfterGC() indicates whether the
+ * referent is still alive. If the referent is is about to be finalized, this
+ * will return false.
+ *
+ * Callers of this method are responsible for updating any state that is
+ * dependent on the object's address. For example, if the object's address is
+ * used as a key in a hashtable, then the object must be removed and
+ * re-inserted with the correct hash.
+ */
+
+extern JS_PUBLIC_API bool JS_AddWeakPointerZonesCallback(
+    JSContext* cx, JSWeakPointerZonesCallback cb, void* data);
+
+extern JS_PUBLIC_API void JS_RemoveWeakPointerZonesCallback(
+    JSContext* cx, JSWeakPointerZonesCallback cb);
+
+extern JS_PUBLIC_API bool JS_AddWeakPointerCompartmentCallback(
+    JSContext* cx, JSWeakPointerCompartmentCallback cb, void* data);
+
+extern JS_PUBLIC_API void JS_RemoveWeakPointerCompartmentCallback(
+    JSContext* cx, JSWeakPointerCompartmentCallback cb);
+
+namespace JS {
+template <typename T>
+class Heap;
+}
+
+extern JS_PUBLIC_API bool JS_UpdateWeakPointerAfterGC(
+    JSTracer* trc, JS::Heap<JSObject*>* objp);
+
+extern JS_PUBLIC_API bool JS_UpdateWeakPointerAfterGCUnbarriered(
+    JSTracer* trc, JSObject** objp);
+
+extern JS_PUBLIC_API void JS_SetGCParameter(JSContext* cx, JSGCParamKey key,
+                                            uint32_t value);
+
+extern JS_PUBLIC_API void JS_ResetGCParameter(JSContext* cx, JSGCParamKey key);
+
+extern JS_PUBLIC_API uint32_t JS_GetGCParameter(JSContext* cx,
+                                                JSGCParamKey key);
+
+extern JS_PUBLIC_API void JS_SetGCParametersBasedOnAvailableMemory(
+    JSContext* cx, uint32_t availMemMB);
+
+/**
+ * Create a new JSString whose chars member refers to external memory, i.e.,
+ * memory requiring application-specific finalization.
+ */
+extern JS_PUBLIC_API JSString* JS_NewExternalStringLatin1(
+    JSContext* cx, const JS::Latin1Char* chars, size_t length,
+    const JSExternalStringCallbacks* callbacks);
+extern JS_PUBLIC_API JSString* JS_NewExternalUCString(
+    JSContext* cx, const char16_t* chars, size_t length,
+    const JSExternalStringCallbacks* callbacks);
+
+/**
+ * Create a new JSString whose chars member may refer to external memory.
+ * If a new external string is allocated, |*allocatedExternal| is set to true.
+ * Otherwise the returned string is either not an external string or an
+ * external string allocated by a previous call and |*allocatedExternal| is set
+ * to false. If |*allocatedExternal| is false, |fin| won't be called.
+ */
+extern JS_PUBLIC_API JSString* JS_NewMaybeExternalStringLatin1(
+    JSContext* cx, const JS::Latin1Char* chars, size_t length,
+    const JSExternalStringCallbacks* callbacks, bool* allocatedExternal);
+extern JS_PUBLIC_API JSString* JS_NewMaybeExternalUCString(
+    JSContext* cx, const char16_t* chars, size_t length,
+    const JSExternalStringCallbacks* callbacks, bool* allocatedExternal);
+
+/**
+ * Similar to JS_NewMaybeExternalStringLatin1.
+ *
+ * Create an external Latin1 string if the utf8 buffer contains only ASCII
+ * chars, otherwise copy the chars into a non-external string.
+ */
+extern JS_PUBLIC_API JSString* JS_NewMaybeExternalStringUTF8(
+    JSContext* cx, const JS::UTF8Chars& utf8,
+    const JSExternalStringCallbacks* callbacks, bool* allocatedExternal);
+
+/**
+ * Return the 'callbacks' arg passed to JS_NewExternalStringLatin1,
+ * JS_NewExternalUCString, JS_NewMaybeExternalStringLatin1,
+ * or JS_NewMaybeExternalUCString.
+ */
+extern JS_PUBLIC_API const JSExternalStringCallbacks*
+JS_GetExternalStringCallbacks(JSString* str);
+
+namespace JS {
+
+extern JS_PUBLIC_API GCReason WantEagerMinorGC(JSRuntime* rt);
+
+extern JS_PUBLIC_API GCReason WantEagerMajorGC(JSRuntime* rt);
+
+extern JS_PUBLIC_API void MaybeRunNurseryCollection(JSRuntime* rt,
+                                                    JS::GCReason reason);
+
+extern JS_PUBLIC_API void RunNurseryCollection(
+    JSRuntime* rt, JS::GCReason reason,
+    mozilla::TimeDuration aSinceLastMinorGC);
+
+extern JS_PUBLIC_API void SetHostCleanupFinalizationRegistryCallback(
+    JSContext* cx, JSHostCleanupFinalizationRegistryCallback cb, void* data);
+
+/**
+ * Clear kept alive objects in JS WeakRef.
+ * https://tc39.es/proposal-weakrefs/#sec-clear-kept-objects
+ */
+extern JS_PUBLIC_API void ClearKeptObjects(JSContext* cx);
+
+inline JS_PUBLIC_API bool NeedGrayRootsForZone(Zone* zoneArg) {
+  shadow::Zone* zone = shadow::Zone::from(zoneArg);
+  return zone->isGCMarkingBlackAndGray() || zone->isGCCompacting();
+}
+
+extern JS_PUBLIC_API bool AtomsZoneIsCollecting(JSRuntime* runtime);
+extern JS_PUBLIC_API bool IsAtomsZone(Zone* zone);
+
+}  // namespace JS
+
+namespace js {
+namespace gc {
+
+/**
+ * Create an object providing access to the garbage collector's internal notion
+ * of the current state of memory (both GC heap memory and GCthing-controlled
+ * malloc memory.
+ */
+extern JS_PUBLIC_API JSObject* NewMemoryInfoObject(JSContext* cx);
+
+/*
+ * Run the finalizer of a nursery-allocated JSObject that is known to be dead.
+ *
+ * This is a dangerous operation - only use this if you know what you're doing!
+ *
+ * This is used by the browser to implement nursery-allocated wrapper cached
+ * wrappers.
+ */
+extern JS_PUBLIC_API void FinalizeDeadNurseryObject(JSContext* cx,
+                                                    JSObject* obj);
+
+} /* namespace gc */
+} /* namespace js */
+
+#ifdef JS_GC_ZEAL
+
+#  define JS_DEFAULT_ZEAL_FREQ 100
+
+extern JS_PUBLIC_API void JS_GetGCZealBits(JSContext* cx, uint32_t* zealBits,
+                                           uint32_t* frequency,
+                                           uint32_t* nextScheduled);
+
+extern JS_PUBLIC_API void JS_SetGCZeal(JSContext* cx, uint8_t zeal,
+                                       uint32_t frequency);
+
+extern JS_PUBLIC_API void JS_UnsetGCZeal(JSContext* cx, uint8_t zeal);
+
+extern JS_PUBLIC_API void JS_ScheduleGC(JSContext* cx, uint32_t count);
+
+#endif
+
+#endif /* js_GCAPI_h */