From 339efd0b9f01848819b83ff10ad1ac031992f2b4 Mon Sep 17 00:00:00 2001
From: Daniel Ehrenberg <littledan@chromium.org>
Date: Tue, 28 May 2019 16:28:51 +0200
Subject: [PATCH 1/3] Update GC observability with WeakRefs

Changing a "must" to "should" here, and referencing the current state
of the WeakRefs proposal (multiple implementation support)
---
 index.bs | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/index.bs b/index.bs
index 47b26037..4a71e025 100644
--- a/index.bs
+++ b/index.bs
@@ -31,6 +31,7 @@ url: https://w3c.github.io/IntersectionObserver/;
     type: dictionary; text: IntersectionObserverInit; url: #dictdef-intersectionobserverinit
 url: https://wicg.github.io/ResizeObserver/;
     type: interface; text: ResizeObserver; url: #resizeobserver
+url: https://dom.spec.whatwg.org/#ref-for-concept-getelementsbytagname; type: interface; text: getElementsByTagName; for: Document
 </pre>
 
 <style>
@@ -81,28 +82,28 @@ object property).
 
 <h3 id="js-gc">Do not expose garbage collection</h3>
 
-There must not be a way for author code to deduce when/if garbage collection of JavaScript objects
-has run.
+Web APIs should not expose a way for author code to deduce when/if garbage collection of JavaScript
+objects has run.
 
-The reason for this is somewhat subtle. If garbage collection timing were observable, then authors
-could easily write code relying on specific garbage collection timing. But this timing is almost
-certainly not the same across user agents, which means the resulting code will be
+Although some APIs may expose garbage collection, such as some implementations of
+{{Document/getElementsByTagName}}, and the JavaScript <a
+href="https://github.com/tc39/proposal-weakrefs">WeakRefs proposal</a> (which has multiple
+implementer support), API designers are strongly encouraged to avoid points in their own APIs that
+depend on this timing.
+
+The reason for this is somewhat subtle. The more that Web API semantics are affected by garbage
+collection timing (or whether objects are collected at all), the more programs will be affected by
+changes in this timing. But user agents differ significantly in both the timing of garbage
+collection and whether certain objects are collected at all, which means the resulting code will be
 non-interoperable. Worse, according to the usual rules of game theory as applied to browsers, this
 kind of scenario could force other user agents to copy the garbage collection timing of the
 original in order to create interoperability. This would cause current garbage collection
 strategies to ossify, preventing improvement in one of the most dynamic areas of JavaScript
 virtual machine technology.
 
-In particular, this means that you can't expose any API that acts as a weak reference, e.g. with a
-property that becomes <code highlight="js">null</code> once garbage collection runs. Such freeing of memory must
-be entirely deterministic.
-
-<div class="note">
-There is some speculative discussion of exposing weak references such that their finalization is
-only observable between event loop turns in this <a
-href="https://github.com/tc39/proposal-weakrefs">stage 1 proposal under discussion at TC39</a>.
-However, this remains contentious and does not yet have consensus in TC39 or among implementers.
-</div>
+In particular, this means that you should not expose any API that acts as a weak reference, e.g. with a
+property that becomes <code highlight="js">null</code> once garbage collection runs. Such freeing of memory
+should be entirely deterministic.
 
 <h2 id="api-surface">API Surface Concerns</h2>
 

From 6d27bbb8279620f6adcea55e5771477e50e3b7d7 Mon Sep 17 00:00:00 2001
From: Daniel Ehrenberg <littledan@chromium.org>
Date: Tue, 28 May 2019 18:30:31 +0200
Subject: [PATCH 2/3] Make example more concrete

---
 index.bs | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/index.bs b/index.bs
index 4a71e025..1b68bc3d 100644
--- a/index.bs
+++ b/index.bs
@@ -101,9 +101,12 @@ original in order to create interoperability. This would cause current garbage c
 strategies to ossify, preventing improvement in one of the most dynamic areas of JavaScript
 virtual machine technology.
 
-In particular, this means that you should not expose any API that acts as a weak reference, e.g. with a
-property that becomes <code highlight="js">null</code> once garbage collection runs. Such freeing of memory
-should be entirely deterministic.
+For example, currently, {{Document/getElementsByTagName}} permits reusing the {{HTMLCollection}}
+which it creates, when it's called with the same receiver and tag name. In practice, engines reuse
+the output if it has not been garbage collected. This creates behavior which differs based on the
+details of garbage collection, which is strongly discouraged. If {{Document/getElementsByTagName}}
+were designed today, the advice to the specification authors would be to either reliably reuse
+the output, or to produce a new {{HTMLCollection}} each time it's invoked.
 
 <h2 id="api-surface">API Surface Concerns</h2>
 

From 2513dbedc8c205a00f458f31c5e5191683bcf305 Mon Sep 17 00:00:00 2001
From: Daniel Ehrenberg <littledan@chromium.org>
Date: Fri, 31 May 2019 14:01:06 +0200
Subject: [PATCH 3/3] Feedback from David

---
 index.bs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/index.bs b/index.bs
index 1b68bc3d..16619334 100644
--- a/index.bs
+++ b/index.bs
@@ -101,6 +101,10 @@ original in order to create interoperability. This would cause current garbage c
 strategies to ossify, preventing improvement in one of the most dynamic areas of JavaScript
 virtual machine technology.
 
+In particular, this means that you shouldn't expose any API that acts as a weak reference, e.g. with a
+property that becomes <code highlight="js">null</code> once garbage collection runs. Such freeing of
+memory should be entirely deterministic.
+
 For example, currently, {{Document/getElementsByTagName}} permits reusing the {{HTMLCollection}}
 which it creates, when it's called with the same receiver and tag name. In practice, engines reuse
 the output if it has not been garbage collected. This creates behavior which differs based on the
@@ -108,6 +112,11 @@ details of garbage collection, which is strongly discouraged. If {{Document/getE
 were designed today, the advice to the specification authors would be to either reliably reuse
 the output, or to produce a new {{HTMLCollection}} each time it's invoked.
 
+The case of {{Document/getElementsByTagName}} is particularly insidious because nothing about
+the API visibly relates to garbage collection details. By contrast, special APIs for this particular
+purpose such as `WeakRef` and `FinalizationGroup` have their GC interaction as a specific part of
+their contract with the developer.
+
 <h2 id="api-surface">API Surface Concerns</h2>
 
 <h3 id="naming-is-hard">Naming things</h3>