Feature/initial reference docs #196
Conversation
reference.md
Outdated
| A `FinalizationRegistry` instance (a "registry") lets you get *cleanup callbacks* after objects registered with the registry are reclaimed. You create the registry passing in the callback: | ||
|
|
||
| ```js | ||
| const registry = new FInalizationRegistry(heldValue => { |
There was a problem hiding this comment.
Fix casing: FinalizationRegistry
reference.md
Outdated
|
|
||
| A finalization registry provides a way to request that a *cleanup callback* get called at some point after an object registered with the registry has been *reclaimed* (garbage collected). (Cleanup callbacks are sometimes called *finalizers*.) | ||
|
|
||
| **NOTE:** The form of this API is under review, see [issue #187](https://github.com/tc39/proposal-weakrefs/pull/187). |
There was a problem hiding this comment.
Probably say here, explicitly, "This document is written in terms of that PR landing."
reference.md
Outdated
| * When the JavaScript realm the objects existed in is being destroyed entirely (for instance, closing a tab in a browser). | ||
| * When the `FinalizationRegistry` instance itself is no longer reachable by JavaScript code. | ||
|
|
||
| See [Use Cases for Cleanup Callbacks](#use-cases-for-cleanup-callbacks) and [Patterns to Avoid With Cleanup Callbacks](#patterns-to-avoid-with-cleanup-callbacks) for more on this topic. |
There was a problem hiding this comment.
These appear to be dead links. Maybe delete this paragraph for now?
reference.md
Outdated
|
|
||
| There are also situations where even implementations that normally call cleanup callbacks are unlikely to call them: | ||
|
|
||
| * When the JavaScript realm the objects existed in is being destroyed entirely (for instance, closing a tab in a browser). |
There was a problem hiding this comment.
I think destruction is more of a per-agent thing than a per-realm thing. But let's just talk about this at a higher level, like, "When the JavaScript program shuts down entirely (for instance, ..."
reference.md
Outdated
|
|
||
| * If your code has just created a WeakRef for a target object, or has gotten a target object from a WeakRef's `deref` method, that target object will not be reclaimed until the end of the current JavaScript [job](https://tc39.es/ecma262/#job) (including any promise reaction jobs that run at the end of a script job). That is, you can only "see" an object get reclaimed between turns of the event loop. This is primarily to avoid making the behavior of any given JavaScript engine's garbage collector apparent in code — because if it were, people would write code relying on that behavior, which would break when the garbage collector's behavior changed. (Garbage collection is a hard problem; JavaScript engine implementers are constantly refining and improving how it works.) | ||
| * If multiple WeakRefs have the same target, they're consistent with one another. The result of calling `deref` on one of them will match the result of calling `deref` on another of them (in the same job), you won't get the target object from one of them but `undefined` from another. | ||
| * If the target of a WeakRef is also in a [`FinalizationRegistry`](#finalizationregistry), the WeakRef's target is cleared *before* any cleanup callback associated with the registry is called. |
There was a problem hiding this comment.
before or at the same time. Maybe it'd be more clear to put this backwards, and as part of the FinalizationGroup notes: it won't be possible, during a finalizer callback, to read a WeakRef and get the object that was registered--these Weakefs will always be undefined.
There was a problem hiding this comment.
I'm happy to move it. :-) But it literally is before, right? In Execution, for a given obj, the agent clears any [[WeakRefTarget]]s of WeakRefs before moving on to finalization for it (Step 1.a comes before Step 1.b). I find it easier to explain and reason about this if I know that when obj is going away / gone, any WeakRefs for it are cleared before any cleanup callbacks for it occur. The "before" here doesn't refer to event turns or anything, just the boring old temporal meaning. :-)
There was a problem hiding this comment.
(I have the other fixes ready to go -- can't believe I missed a couple of those -- just waiting to resolve this point.)
There was a problem hiding this comment.
Those steps all happen "atomically", so it's not really before.
There was a problem hiding this comment.
Okay, will update.
|
Thank you for the contribution! |
|
Nice work - microsoft/TypeScript#38232 turns this into a d.ts file for the upcoming TypeScript 4.0 release too 👍 |
Doesn't go into use cases or patterns/anti-patterns yet.