1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
//! §26.1's `WeakRef` and §26.2's `FinalizationRegistry` — one reference the collector will not
//! follow, and a list of them.
//!
//! # What makes these different from §24.3's weak collections
//!
//! A `WeakMap` entry is an *ephemeron*: its value lives while its key does. These two hold a
//! reference that is simply not followed, and the observable consequence is a `deref` that starts
//! answering `undefined`. Nothing else in the heap has that shape, which is why it is a type of
//! its own rather than another [`crate::heap::CollectionKind`].
//!
//! # Why `deref` can be answered by asking the arena
//!
//! `heap.object(id).is_none()` is exactly §26.1.3.2's question, with no extra bookkeeping here and
//! no chance of answering about the wrong object — but **not** for the reason this paragraph used
//! to give. It said the slot was never reused, so an empty one could only mean "collected". DR-0019
//! reuses it, and the guarantee is now DR-0019's own: the handle carries the generation its slot
//! was on, [`crate::heap::arena::Arena::get`] compares them, and a handle to a collected object
//! answers `None` however many times its slot has been handed out since.
//!
//! So the free-list-needs-a-generation cost the old text called future is one already paid, and the
//! behaviour is unchanged. Recorded at this length because the stale version read as an argument
//! that this file's soundness *depended* on slots never being reused, which would have made
//! `deref` a use-after-free the moment they were.
//!
//! # Why the cleanup callback never runs
//!
//! §26.2 lets an implementation call it "at any time" and permits it never to be called at all.
//! Choosing a moment means deciding when to collect, which §9.10's note leaves entirely to the
//! implementation and which ViperJS has not decided — collection is driven by the embedder. So a
//! registry here holds its cells, drops the ones whose target has gone, and calls nothing. That is
//! a conforming choice rather than a gap, and it is the only one available until there is a
//! measured answer to when collection should happen.
use crate;
use crateValue;
/// A value §7.2.10 `CanBeHeldWeakly` allows — an Object, or an unregistered Symbol.
///
/// A type rather than a checked [`Value`], because every one of §26's slots holds one and none of
/// them can hold anything else. Written as a `Value` instead, each read would have an arm for
/// "some other primitive" that no program could reach: `WeakRef`'s constructor refuses those and
/// so does `register`, so the arm would be a branch no test could distinguish from its absence.
/// Saying it in the type removes the question rather than answering it four times.
///
/// Equality is *identity*, which is what the derive gives: two of these are equal exactly when
/// they are the same handle. That is `SameValue` restricted to what may be held — the general
/// relation needs the heap only because two Strings are equal by their contents, and a String can
/// never be here.
/// One `register` call — §26.2.1.1's `[[Cells]]` entry.
/// §26.2's `[[CleanupCallback]]` and `[[Cells]]`.
/// §26.1's `[[WeakRefTarget]]` or §26.2's `[[Cells]]`, and which of the two this is.