Web/JavaScript/Reference/Global_Objects/FinalizationRegistry を更新 (#1636)

- Markdown に変更
- 2021/07/21 時点の英語版に同期

2 files changed, 129 insertions, 150 deletions

diff --git a/files/ja/web/javascript/reference/global_objects/finalizationregistry/index.html b/files/ja/web/javascript/reference/global_objects/finalizationregistry/index.html
deleted file mode 100644
index 1e03707820..0000000000
--- a/files/ja/web/javascript/reference/global_objects/finalizationregistry/index.html
+++ /dev/null
@@ -1,150 +0,0 @@
----
-title: FinalizationRegistry
-slug: Web/JavaScript/Reference/Global_Objects/FinalizationRegistry
-tags:
-  - Class
-  - FinalizationRegistry
-  - JavaScript
-  - Reference
-translation_of: Web/JavaScript/Reference/Global_Objects/FinalizationRegistry
----
-<div>{{JSRef}}</div>
-
-<p><strong><code>FinalizationRegistry</code></strong> オブジェクトにより、オブジェクトがガベージコレクションで回収されるときにコールバックを要求することができます。</p>
-
-<h2 id="Description" name="Description">解説</h2>
-
-<p><code>FinalizationRegistry</code> は、レジストリに登録されているオブジェクトが<em>回収</em>される (ガベージコレクションされる) 時に<em>クリーンアップコールバック</em>を要求する方法を提供します。(クリーンアップコールバックは<em>ファイナライザー</em>と呼ばれることもあります。)</p>
-
-<div class="note">
-<p><strong>注:</strong> Cleanup callbacks should not be used for essential program logic. 詳しくは <a href="#Notes_on_cleanup_callbacks">Notes on cleanup callbacks</a> を見てください。</p>
-</div>
-
-<p>コールバックで渡すレジストリを作成します。</p>
-
-<pre class="brush: js notranslate">const registry = new FinalizationRegistry(heldValue =&gt; {
-  // ....
-});
-</pre>
-
-<p>次に、 <code>register</code> メソッドを呼び出して、クリーンアップコールバックを行いたいオブジェクトを登録し、そのオブジェクトと<em>保持値</em>を渡します。</p>
-
-<pre class="brush: js notranslate">registry.register(theObject, "some value");
-</pre>
-
-<p>レジストリがオブジェクトへの強い参照を保持すると、目的に反してしまうので、 (レジストリが強い参照を保持していれば、そのオブジェクトは決して回収されない)、強い参照は保持はしません。</p>
-
-<p><code>theObject</code> が回収された場合、クリーンアップコールバックは、指定した<em>保持値</em> (上では <code>"some value"</code>) で呼び出される可能性があります。保持値は、プリミティブでもオブジェクトでも、 <code>undefined</code> であっても構いません。保持値がオブジェクトの場合、レジストリはその値への<em>強い</em>参照を保持します (これにより、後でクリーンアップコールバックに渡すことができます)。</p>
-
-<p>オブジェクトの登録を解除したい場合は、三番目の値を渡します。 これは、後でレジストリのレジストリの <code>unregister</code> 関数をコールしてオブジェクトの登録を解除する際に使用する<em>登録解除トークン</em>です。レジストリは、登録解除トークンへの弱い参照のみを保持します。</p>
-
-<p>よくオブジェクト自身が登録解除トークンとして使われ、これは良い結果になります。</p>
-
-<pre class="brush: js notranslate">registry.register(theObject, "some value", theObject);
-// ...some time later, if you don't care about `theObject` anymore...
-registry.unregister(theObject);
-</pre>
-
-<p>ただし、同じオブジェクトである必要はありません。異なるものでも構いません。</p>
-
-<pre class="brush: js notranslate">registry.register(theObject, "some value", tokenObject);
-// ...some time later, if you don't care about `theObject` anymore...
-registry.unregister(tokenObject);
-</pre>
-
-<h2 id="Constructor" name="Constructor">コンストラクター</h2>
-
-<dl>
- <dt>{{jsxref("FinalizationRegistry/FinalizationRegistry", "FinalizationRegistry()")}}</dt>
- <dd>新しい <code>FinalizationRegistry</code> オブジェクト生成します。</dd>
-</dl>
-
-<h2 id="Instance_methods" name="Instance_methods">インスタンスメソッド</h2>
-
-<dl>
- <dt>{{jsxref("FinalizationRegistry.register", "FinalizationRegistry.prototype.register()")}}</dt>
- <dd>Registers an object with the registry in order to get a cleanup callback when/if the object is garbage-collected.</dd>
- <dt>{{jsxref("FinalizationRegistry.unregister", "FinalizationRegistry.prototype.unregister()")}}</dt>
- <dd>Unregisters an object from the registry.</dd>
- <dt>{{jsxref("FinalizationRegistry.cleanupSome", "FinalizationRegistry.prototype.cleanupSome()")}}</dt>
- <dd><em>(Optional method.)</em> Proactively requests cleanup callbacks for reclaimed objects.</dd>
-</dl>
-
-<h2 id="Avoid_where_possible" name="Avoid_where_possible">Avoid where possible</h2>
-
-<p>Correct use of <code>FinalizationRegistry</code> takes careful thought, and it's best avoided if possible. It's also important to avoid relying on any specific behaviors not guaranteed by the specification. When, how, and whether garbage collection occurs is down to the implementation of any given JavaScript engine. Any behavior you observe in one engine may be different in another engine, in another version of the same engine, or even in a slightly different situation with the same version of the same engine. Garbage collection is a hard problem that JavaScript engine implementers are constantly refining and improving their solutions to.</p>
-
-<p>Here are some specific points that the authors of the WeakRef proposal that FinalizationRegistry is part of included in its <a href="https://github.com/tc39/proposal-FinalizationRegistrys/blob/master/README.md">explainer document</a>:</p>
-
-<blockquote>
-<p><a href="https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)">Garbage collectors</a> are complicated. If an application or library depends on GC cleaning up a FinalizationRegistry or calling a finalizer [cleanup callback] in a timely, predictable manner, it's likely to be disappointed: the cleanup may happen much later than expected, or not at all. Sources of variability include:</p>
-
-<ul>
- <li>One object might be garbage-collected much sooner than another object, even if they become unreachable at the same time, e.g., due to generational collection.</li>
- <li>Garbage collection work can be split up over time using incremental and concurrent techniques.</li>
- <li>Various runtime heuristics can be used to balance memory usage, responsiveness.</li>
- <li>The JavaScript engine may hold references to things which look like they are unreachable (e.g., in closures, or inline caches).</li>
- <li>Different JavaScript engines may do these things differently, or the same engine may change its algorithms across versions.</li>
- <li>Complex factors may lead to objects being held alive for unexpected amounts of time, such as use with certain APIs.</li>
-</ul>
-</blockquote>
-
-<h2 id="Notes_on_cleanup_callbacks" name="Notes_on_cleanup_callbacks">Notes on cleanup callbacks</h2>
-
-<p>Some notes on cleanup callbacks:</p>
-
-<ul>
- <li>Developers shouldn't rely on cleanup callbacks for essential program logic. Cleanup callbacks may be useful for reducing memory usage across the course of a program, but are unlikely to be useful otherwise.</li>
- <li>A conforming JavaScript implementation, even one that does garbage collection, is not required to call cleanup callbacks. When and whether it does so is entirely down to the implementation of the JavaScript engine. When a registered object is reclaimed, any cleanup callbacks for it may be called then, or some time later, or not at all.</li>
- <li>It's likely that major implementations will call cleanup callbacks at some point during execution, but those calls may be substantially after the related object was reclaimed.</li>
- <li>There are also situations where even implementations that normally call cleanup callbacks are unlikely to call them:
-  <ul>
-   <li>When the JavaScript program shuts down entirely (for instance, closing a tab in a browser).</li>
-   <li>When the <code>FinalizationRegistry</code> instance itself is no longer reachable by JavaScript code.</li>
-  </ul>
- </li>
-</ul>
-
-<h2 id="Examples" name="Examples">例</h2>
-
-<h3 id="Creating_a_new_registry" name="Creating_a_new_registry">Creating a new registry</h3>
-
-<p>You create the registry passing in the callback:</p>
-
-<pre class="brush: js notranslate">const registry = new FinalizationRegistry(heldValue =&gt; {
-  // ....
-});
-</pre>
-
-<h3 id="Registering_objects_for_cleanup" name="Registering_objects_for_cleanup">Registering objects for cleanup</h3>
-
-<p>Then you register any objects you want a cleanup callback for by calling the `register` method, passing in the object and a *held value* for it:</p>
-
-<pre class="brush: js notranslate">registry.register(theObject, "some value");</pre>
-
-<h2 id="Specifications" name="Specifications">仕様書</h2>
-
-<table class="standard-table">
- <thead>
-  <tr>
-   <th scope="col">仕様書</th>
-  </tr>
- </thead>
- <tbody>
-  <tr>
-   <td>{{SpecName('WeakRefs', '#sec-finalization-registry-objects', 'FinalizationRegistry')}}</td>
-  </tr>
- </tbody>
-</table>
-
-<h2 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h2>
-
-<p>{{Compat("javascript.builtins.FinalizationRegistry")}}</p>
-
-<h2 id="See_also" name="See_also">関連情報</h2>
-
-<ul>
- <li>{{jsxref("WeakRef")}}</li>
- <li>{{jsxref("WeakSet")}}</li>
- <li>{{jsxref("WeakMap")}}</li>
-</ul>
diff --git a/files/ja/web/javascript/reference/global_objects/finalizationregistry/index.md b/files/ja/web/javascript/reference/global_objects/finalizationregistry/index.md
new file mode 100644
index 0000000000..5edff7c2eb
--- /dev/null
+++ b/files/ja/web/javascript/reference/global_objects/finalizationregistry/index.md
@@ -0,0 +1,129 @@
+---
+title: FinalizationRegistry
+slug: Web/JavaScript/Reference/Global_Objects/FinalizationRegistry
+tags:
+  - Class
+  - FinalizationRegistry
+  - JavaScript
+  - Reference
+browser-compat: javascript.builtins.FinalizationRegistry
+translation_of: Web/JavaScript/Reference/Global_Objects/FinalizationRegistry
+---
+{{JSRef}}
+
+**`FinalizationRegistry`** オブジェクトにより、オブジェクトがガベージコレクションで回収されるときにコールバックを要求することができます。
+
+## 解説
+
+`FinalizationRegistry` は、レジストリーに登録されているオブジェクトが*回収*される (ガベージコレクションされる) 時に*クリーンアップコールバック*を要求する方法を提供します。(クリーンアップコールバックは*ファイナライザー*と呼ばれることもあります。)</p>
+
+> **Note:** クリーンアップコールバックは、重要なプログラムロジックには使用しないでください。詳細は、[クリーンアップコールバックに関する注意事項](#notes_on_cleanup_callbacks)を参照してください。
+
+コールバックで渡すレジストリーを作成します。
+
+```js
+const registry = new FinalizationRegistry(heldValue => {
+  // ....
+});
+```
+
+次に、 `register` メソッドを呼び出して、クリーンアップコールバックを行いたいオブジェクトを登録し、そのオブジェクトと*保持値*を渡します。
+
+```js
+registry.register(theObject, "some value");
+```
+
+レジストリーがオブジェクトへの強い参照を保持すると、目的に反してしまうので、 (レジストリーが強い参照を保持していれば、そのオブジェクトは決して回収されない)、強い参照は保持はしません。
+
+`theObject` が回収された場合、クリーンアップコールバックは、指定した*保持値* (上記の `"some value"`) で呼び出される可能性があります。保持値は、プリミティブでもオブジェクトでも、 `undefined` であっても構いません。保持値がオブジェクトの場合、レジストリーはその値への*強い*参照を保持します (これにより、後でクリーンアップコールバックに渡すことができます)。
+
+オブジェクトの登録を解除したい場合は、三番目の値を渡します。 これは、後でレジストリのレジストリの `unregister` 関数を呼び出してオブジェクトの登録を解除する際に使用する*登録解除トークン*です。レジストリーは、登録解除トークンへの弱い参照のみを保持します。
+
+よくオブジェクト自身が登録解除トークンとして使われ、これは良い結果になります。
+
+```js
+registry.register(theObject, "some value", theObject);
+// ...some time later, if you don't care about `theObject` anymore...
+registry.unregister(theObject);
+```
+
+ただし、同じオブジェクトである必要はありません。異なるものでも構いません。
+
+```js
+registry.register(theObject, "some value", tokenObject);
+// ...some time later, if you don't care about `theObject` anymore...
+registry.unregister(tokenObject);
+```
+
+## コンストラクター
+
+- {{jsxref("FinalizationRegistry/FinalizationRegistry", "FinalizationRegistry()")}}
+  - : 新しい `FinalizationRegistry` オブジェクトを生成します。
+
+## インスタンスメソッド
+
+- {{jsxref("FinalizationRegistry.register", "FinalizationRegistry.prototype.register()")}}
+  - : オブジェクトをレジストリーに登録して、オブジェクトがガベージコレクションされたときにクリーンアップコールバックが実行できるようにします。
+- {{jsxref("FinalizationRegistry.unregister", "FinalizationRegistry.prototype.unregister()")}}
+  - : オブジェクトをレジストリーから登録解除します。
+
+## できるだけ使用しない
+
+`FinalizationRegistry` を正しく使用するには慎重に検討する必要があるため、できるだけ使用しない方がいいでしょう。また、仕様で保証されていない特定の動作に依存しないようにすることも重要です。ガベージコレクションがいつ、どのように、どのように行われるかは、それぞれの JavaScript エンジンの実装に依存します。あるエンジンで観察された動作が、別のエンジンや同じエンジンの別のバージョンでは異なるかもしれませんし、同じエンジンの同じバージョンでも若干異なる状況になるかもしれません。ガベージコレクションは、 JavaScript エンジンの実装者がその解決策を常に改良し続けている難しい問題なのです。
+
+ここでは、 `FinalizationRegistry` が含まれている WeakRef の提案の著者が、その[説明文書](https://github.com/tc39/proposal-weakrefs/blob/master/reference.md)に盛り込んだ具体的なポイントを紹介します。
+
+> [ガベージコレクター](<https://ja.wikipedia.org/wiki/%E3%82%AC%E3%83%99%E3%83%BC%E3%82%B8%E3%82%B3%E3%83%AC%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3>) は複雑です。アプリケーションやライブラリーが、ガベージコレクターによる `FinalizationRegistry` のクリーンアップやファイナライザー [クリーンアップコールバック] の呼び出しをタイムリーに予測可能な方法で行うことに依存している場合、期待を裏切られる可能性があります。クリーンアップが予想よりもずっと遅く行われたり、まったく行われなかったりすることがあります。変化する原因には次のようなものがあります。
+>
+> - あるオブジェクトが他のオブジェクトよりも早くガベージコレクションされることがあります。これは、世代別コレクションなどにより、同時に到達できなくなったとしても同様です。
+> - ガベージコレクションの作業は、差分技術やコンカレント技術を使って時間をかけて分割される可能性があります。
+> - メモリ使用量や応答性のバランスをとるために、さまざまなランタイムヒューリスティックが使用されることがあります。
+> - JavaScript エンジンは、 (クロージャやインラインキャッシュなどで) 到達できないように見えるものへの参照を保持することがあります。
+> - JavaScript エンジンによっては、これらの処理が異なる場合がありますし、同じエンジンでもバージョンによってアルゴリズムが変わる場合があります。
+> - 複雑な要因により、特定の API を使用する場合などに、オブジェクトが予想外の時間だけ保持されることがあります。
+
+## クリーンアップコールバックに関する注意点
+
+クリーンアップコールバックには、いくつかの注意点があります。
+
+-  開発者は、重要なプログラムロジックをクリーンアップコールバックに頼るべきではありません。クリーンアップコールバックは、プログラムの途中でメモリー使用量を削減するのに役立つかもしれませんが、それ以外ではほとんど役に立ちません。
+- 適合する JavaScript の実装は、たとえガベージコレクションを行うものであっても、クリーンアップコールバックを呼び出すとは限りません。いつ、どのように呼び出すかは、 JavaScript エンジンの実装に完全に依存します。登録されたオブジェクトが回収されたとき、そのオブジェクトのためのクリーンアップコールバックは、そのときに呼ばれるかもしれないし、しばらくしてから呼ばれるかもしれないし、まったく呼ばれないかもしれません。
+- 多くの実装では、実行中のどこかの時点でクリーンアップコールバックが呼び出されると思われますが、それらの呼び出しは関連オブジェクトが再取得された後に実質的に行われるかもしれません。
+- また、通常はクリーンアップコールバックを呼び出す実装であっても、状況によっては呼び出さない可能性もあります。
+
+  - JavaScript プログラムが完全にシャットダウンされたとき (たとえば、ブラウザーのタブを閉じるなど)。
+  - `FinalizationRegistry` インスタンス自体が JavaScript コードからアクセスできなくなったとき。
+
+## 例
+
+### 新しいレジストリーの生成
+
+コールバックを渡すことでレジストリーを作成することができます。
+
+```js
+const registry = new FinalizationRegistry(heldValue => {
+  // ....
+});
+```
+
+### クリーンアップのためにオブジェクトを登録
+
+そして、クリーンアップコールバックを呼び出す任意のオブジェクトを登録するには、 `register` メソッドを呼び出して、そのオブジェクトと*保持値*を渡します。
+
+```js
+registry.register(theObject, "some value");
+```
+
+## 仕様書
+
+{{Specifications}}
+
+## ブラウザーの互換性
+
+{{Compat}}
+
+## 関連情報
+
+- {{jsxref("WeakRef")}}
+- {{jsxref("WeakSet")}}
+- {{jsxref("WeakMap")}}