From 12ff368a40e94fbfa79dffcae70f0193b5150bc1 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 1 Aug 2021 01:22:05 +0900 Subject: Web/JavaScript/Reference/Global_Objects/FinalizationRegistry を更新 (#1636) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Markdown に変更 - 2021/07/21 時点の英語版に同期 --- .../global_objects/finalizationregistry/index.html | 150 --------------------- .../global_objects/finalizationregistry/index.md | 129 ++++++++++++++++++ 2 files changed, 129 insertions(+), 150 deletions(-) delete mode 100644 files/ja/web/javascript/reference/global_objects/finalizationregistry/index.html create mode 100644 files/ja/web/javascript/reference/global_objects/finalizationregistry/index.md (limited to 'files/ja/web/javascript/reference') 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 ---- -
{{JSRef}}
- -

FinalizationRegistry オブジェクトにより、オブジェクトがガベージコレクションで回収されるときにコールバックを要求することができます。

- -

解説

- -

FinalizationRegistry は、レジストリに登録されているオブジェクトが回収される (ガベージコレクションされる) 時にクリーンアップコールバックを要求する方法を提供します。(クリーンアップコールバックはファイナライザーと呼ばれることもあります。)

- -
-

注: Cleanup callbacks should not be used for essential program logic. 詳しくは Notes on cleanup callbacks を見てください。

-
- -

コールバックで渡すレジストリを作成します。

- -
const registry = new FinalizationRegistry(heldValue => {
-  // ....
-});
-
- -

次に、 register メソッドを呼び出して、クリーンアップコールバックを行いたいオブジェクトを登録し、そのオブジェクトと保持値を渡します。

- -
registry.register(theObject, "some value");
-
- -

レジストリがオブジェクトへの強い参照を保持すると、目的に反してしまうので、 (レジストリが強い参照を保持していれば、そのオブジェクトは決して回収されない)、強い参照は保持はしません。

- -

theObject が回収された場合、クリーンアップコールバックは、指定した保持値 (上では "some value") で呼び出される可能性があります。保持値は、プリミティブでもオブジェクトでも、 undefined であっても構いません。保持値がオブジェクトの場合、レジストリはその値への強い参照を保持します (これにより、後でクリーンアップコールバックに渡すことができます)。

- -

オブジェクトの登録を解除したい場合は、三番目の値を渡します。 これは、後でレジストリのレジストリの unregister 関数をコールしてオブジェクトの登録を解除する際に使用する登録解除トークンです。レジストリは、登録解除トークンへの弱い参照のみを保持します。

- -

よくオブジェクト自身が登録解除トークンとして使われ、これは良い結果になります。

- -
registry.register(theObject, "some value", theObject);
-// ...some time later, if you don't care about `theObject` anymore...
-registry.unregister(theObject);
-
- -

ただし、同じオブジェクトである必要はありません。異なるものでも構いません。

- -
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()")}}
-
Registers an object with the registry in order to get a cleanup callback when/if the object is garbage-collected.
-
{{jsxref("FinalizationRegistry.unregister", "FinalizationRegistry.prototype.unregister()")}}
-
Unregisters an object from the registry.
-
{{jsxref("FinalizationRegistry.cleanupSome", "FinalizationRegistry.prototype.cleanupSome()")}}
-
(Optional method.) Proactively requests cleanup callbacks for reclaimed objects.
-
- -

Avoid where possible

- -

Correct use of FinalizationRegistry 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.

- -

Here are some specific points that the authors of the WeakRef proposal that FinalizationRegistry is part of included in its explainer document:

- -
-

Garbage collectors 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:

- - -
- -

Notes on cleanup callbacks

- -

Some notes on cleanup callbacks:

- - - -

例

- -

Creating a new registry

- -

You create the registry passing in the callback:

- -
const registry = new FinalizationRegistry(heldValue => {
-  // ....
-});
-
- -

Registering objects for cleanup

- -

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:

- -
registry.register(theObject, "some value");
- -

仕様書

- - - - - - - - - - - - -
仕様書
{{SpecName('WeakRefs', '#sec-finalization-registry-objects', 'FinalizationRegistry')}}
- -

ブラウザーの互換性

- -

{{Compat("javascript.builtins.FinalizationRegistry")}}

- -

関連情報

- - 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` は、レジストリーに登録されているオブジェクトが*回収*される (ガベージコレクションされる) 時に*クリーンアップコールバック*を要求する方法を提供します。(クリーンアップコールバックは*ファイナライザー*と呼ばれることもあります。)

+ +> **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)に盛り込んだ具体的なポイントを紹介します。 + +> [ガベージコレクター]() は複雑です。アプリケーションやライブラリーが、ガベージコレクターによる `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")}} -- cgit v1.2.3-54-g00ecf