【PHP8.x】gc_collect_cycles関数の使い方

<?php

/**
 * 循環参照を発生させるためのシンプルなクラスを定義します。
 */
class CycleObject
{
    // このプロパティが他のCycleObjectインスタンスを参照します。
    public ?CycleObject $reference = null;
    public string $name;

    /**
     * コンストラクタでオブジェクトの作成をログに記録します。
     */
    public function __construct(string $name)
    {
        $this->name = $name;
        echo "{$this->name} が作成されました。\n";
    }

    /**
     * デストラクタでオブジェクトの破棄をログに記録します。
     * 循環参照がある場合、すぐに呼び出されないことがあります。
     */
    public function __destruct()
    {
        echo "{$this->name} が破棄されました。\n";
    }
}

/**
 * gc_collect_cycles() 関数の動作をデモンストレーションします。
 * 到達不能な循環参照がガベージコレクタによってどのように解放されるかを示します。
 */
function demonstrateGcCollectCycles(): void
{
    echo "--- ガベージコレクションのデモンストレーション開始 ---\n";

    // PHPのガベージコレクタは通常、自動的に動作しますが、
    // このデモンストレーションでは手動での収集を明確にするため、
    // まず自動収集機能を一時的に無効化します。
    gc_disable();
    echo "ガベージコレクタの自動収集を無効化しました。\n";

    // 循環参照を作成するために2つのオブジェクトを生成します。
    $objA = new CycleObject('Object A');
    $objB = new CycleObject('Object B');

    // objA が objB を参照し、objB が objA を参照することで、循環参照を作成します。
    $objA->reference = $objB;
    $objB->reference = $objA;
    echo "Object A と Object B の間で循環参照を作成しました。\n";

    // $objA と $objB 変数への外部からの参照を解除します。
    // この時点では、循環参照があるため、これらのオブジェクトはPHPの参照カウントでは解放されず、
    // __destruct メソッドも呼び出されません。これらが「到達不能な」循環参照になります。
    unset($objA);
    unset($objB);
    echo "外部参照を解除しました。循環参照オブジェクトはまだメモリに残っています。\n";
    echo "（この時点で '破棄されました' メッセージが表示されないことを確認してください）\n";

    // 自動収集を再度有効にします。これで gc_collect_cycles() が動作可能になります。
    gc_enable();
    echo "ガベージコレクタの自動収集を有効化しました。\n";

    // gc_collect_cycles() を呼び出し、到達不能な循環参照を検出して解放します。
    // 戻り値は、解放された循環参照オブジェクトの数です。
    $collected = gc_collect_cycles();
    echo "gc_collect_cycles() を実行しました。\n";

    if ($collected > 0) {
        echo "結果: {$collected} 個の循環参照オブジェクトが収集され、解放されました。\n";
    } else {
        echo "結果: 収集された循環参照オブジェクトはありませんでした。\n";
    }

    echo "--- ガベージコレクションのデモンストレーション終了 ---\n";
}

// デモンストレーション関数を実行します。
demonstrateGcCollectCycles();

?>

PHP 8.4.12 で利用できる gc_collect_cycles 関数は、PHPのメモリ管理において重要な役割を担う内部関数です。PHPのオブジェクトは通常、「参照カウント」という仕組みでメモリが管理され、そのオブジェクトへの参照がすべてなくなると自動的にメモリから解放されます。しかし、オブジェクト同士がお互いを参照し合う「循環参照」が発生した場合、たとえ外部から誰もそのオブジェクトを参照していなくても、参照カウントがゼロにならないため、メモリ上に残り続けてしまうことがあります。

gc_collect_cycles 関数は、このような到達不能な循環参照を検出し、強制的にメモリから解放するために使用されます。この関数には引数はなく、呼び出すだけでガベージコレクタがメモリをスキャンし、到達不可能になった循環参照オブジェクト群を収集します。戻り値として、この処理によって実際に解放された循環参照オブジェクトの数を整数（int）で返します。

サンプルコードでは、gc_disable() で一時的にガベージコレクタの自動収集を無効にした後、意図的に循環参照を作成し、その外部参照を unset() で解除しています。この状態ではオブジェクトはメモリに残ったままですが、gc_collect_cycles() を呼び出すことで、循環参照が解消され、オブジェクトが破棄される様子が示されています。これにより、メモリリークのリスクを低減し、システムの安定稼働に貢献します。