【Node.js24.x】Object::FinalizationRegistry()メソッドの使い方

FinalizationRegistryメソッドは、JavaScriptのガベージコレクション機能と連携し、オブジェクトがメモリから解放される直前に特定のクリーンアップ処理を実行するメソッドです。これは、プログラムが不要になったメモリを自動的に解放する「ガベージコレクション」のタイミングを利用して、そのオブジェクトに関連する後処理を行うための仕組みを提供します。

例えば、ファイルを開いたまま閉じ忘れたり、ネットワーク接続を確立したまま切断し忘れたりといった、外部リソースの解放忘れを防ぐ補助的な目的で利用されます。FinalizationRegistryのインスタンスを生成し、監視したいオブジェクトとそのオブジェクトが回収された際に実行するコールバック関数、そしてそのコールバック関数に渡す情報を登録します。ガベージコレクターが登録されたオブジェクトを検出し、それがメモリから削除されることが決定されると、FinalizationRegistryは非同期に登録されたコールバック関数を呼び出し、クリーンアップ処理を実行させます。

しかし、ガベージコレクションの実行タイミングはシステムによって保証されないため、FinalizationRegistryは決定的なリソース管理には適していません。重要なリソースの解放は、try...finallyブロックや、より明示的なクローズ処理など、確実な方法で管理することが推奨されます。この機能は主に、補助的なクリーンアップやデバッグ用途に役立つものです。

Copy
1const cleanupCallback = (heldValue) => {
2  // オブジェクトがガベージコレクションされた後に非同期で実行されるコールバック関数です。
3  // heldValue には、registry.register() メソッドの第2引数で指定された値が渡されます。
4};
5
6// FinalizationRegistry クラスの新しいインスタンスを作成します。
7// コンストラクタには、クリーンアップコールバック関数を渡します。
8const registry = new FinalizationRegistry(cleanupCallback);
9
10// 監視したいオブジェクトを作成します。
11// このオブジェクトへの参照が全てなくなると、ガベージコレクションの対象になります。
12const objectToMonitor = {};
13
14// 監視対象のオブジェクトを FinalizationRegistry に登録します。
15// 第1引数: 監視したいオブジェクト (WeakRef のターゲットとして内部的に保持されます)
16// 第2引数: ガベージコレクション後に cleanupCallback に渡される値 (heldValue)
17registry.register(objectToMonitor, '監視対象Aの関連データ');

cleanupCallback

• cleanupCallback: function: オブジェクトがファイナライズされる際に実行されるコールバック関数。この関数は、ファイナライズされるオブジェクトのキーと、そのオブジェクトの参照がなくなった際に保持されていた値（もしあれば）を引数として受け取ります。

FinalizationRegistry

FinalizationRegistryは、オブジェクトがガベージコレクション（不要になったメモリの解放処理）された際に、指定したコールバック関数を実行するためのオブジェクトです。