PHPのジェネレータ：yield、yield fromとメモリ節約

ジェネレータとは、yieldを含む関数です。呼び出しても本体は実行されず、foreachでループできるGeneratorオブジェクトが返ります。yield $valueはそれぞれ1つの値をループに渡し、ループが次を求めるまで関数を一時停止します。そのため値は、先に配列に集められるのではなく、1つずつ作られます。

<?php
function countTo(int $n): Generator
{
    for ($i = 1; $i <= $n; $i++) {
        echo "(making $i) ";
        yield $i;
    }
}

foreach (countTo(3) as $number) {
    echo "got $number\n";
}

出力はジェネレータとループの間を行き来します。各値は、ループが求めたときにだけ作られます。

ジェネレータはメモリを節約する

range(1, 1000000)は、ループが始まる前に100万個の整数の配列を作ります。同じ数をyieldするジェネレータは、一度に1つしか持ちません。実行して、それぞれに必要なメモリを比べてください。

<?php
function numbers(int $max): Generator
{
    for ($i = 1; $i <= $max; $i++) {
        yield $i;
    }
}

$start = memory_get_usage();
$sum = 0;
foreach (range(1, 1_000_000) as $n) {
    $sum += $n;
}
$arrayPeak = memory_get_peak_usage() - $start;

memory_reset_peak_usage();
$start = memory_get_usage();
$sum2 = 0;
foreach (numbers(1_000_000) as $n) {
    $sum2 += $n;
}
$genPeak = memory_get_peak_usage() - $start;

printf("array:     sum %d, extra memory %.1f MB\n", $sum, $arrayPeak / 1048576);
printf("generator: sum %d, extra memory %.1f MB\n", $sum2, $genPeak / 1048576);

どちらのループも同じ合計500000500000を出力しますが、配列版はextra memory 16.0 MB、ジェネレータはextra memory 0.0 MBと報告します。データが増えるほど差は広がります。大きなファイル、データベースの結果、APIのページにジェネレータが役立つのも同じ考え方からで、1件処理して捨て、次の1件を取るのです。

キーと値をyieldする

yield $key => $valueは、foreach ($gen as $key => $value)が受け取るキーを設定します。キーがなければ、ジェネレータはリストのように値に0から番号を振ります。よくある使い方は、行番号付きでファイルを1行ずつ読むことです。

<?php
file_put_contents('log.txt', "boot ok\nERROR disk full\nuser login\nERROR timeout\n");

function readLines(string $path): Generator
{
    $handle = fopen($path, 'r');
    $lineNo = 0;
    while (($line = fgets($handle)) !== false) {
        $lineNo++;
        yield $lineNo => rtrim($line, "\n");
    }
    fclose($handle);
}

foreach (readLines('log.txt') as $no => $line) {
    if (str_starts_with($line, 'ERROR')) {
        echo "line $no: $line\n";
    }
}

メモリにあるのは一度に1行だけなので、同じ関数で2 GBのログファイルも扱えます。ここで使っているファイル関数はfopen()とfgets()で扱っています。

無限の数列と遅延パイプライン

ジェネレータは、使う側が求めるところまでしか実行されないので、永遠にループしてもかまいません。breakで止めるか、最初のいくつかの値を取る別のジェネレータで包みます。小さなジェネレータをつなげると、すべての段階が遅延評価されるパイプラインになります。

<?php
function fibonacci(): Generator
{
    [$a, $b] = [0, 1];
    while (true) {
        yield $a;
        [$a, $b] = [$b, $a + $b];
    }
}

function take(iterable $items, int $n): Generator
{
    if ($n <= 0) {
        return;
    }
    foreach ($items as $item) {
        yield $item;
        if (--$n === 0) {
            return;
        }
    }
}

function filter(iterable $items, callable $keep): Generator
{
    foreach ($items as $item) {
        if ($keep($item)) {
            yield $item;
        }
    }
}

echo implode(' ', iterator_to_array(take(fibonacci(), 10), false)), "\n";

$evenFibs = take(filter(fibonacci(), fn($x) => $x % 2 === 0), 6);
echo implode(' ', iterator_to_array($evenFibs, false)), "\n";

fibonacci()は自分では決して終わりませんが、プログラムは終了します。take()が求めた数のあとで要求をやめ、その先は何も計算されないからです。

yield from：別のジェネレータに任せる

yield fromは、配列、イテレータ、別のジェネレータのすべての値を受け渡します。ジェネレータを小さなものに分けたり、ネストした構造を再帰的にたどったりする方法です。

<?php
function flatten(array $items): Generator
{
    foreach ($items as $item) {
        if (is_array($item)) {
            yield from flatten($item);   // recurse
        } else {
            yield $item;
        }
    }
}

$nested = [1, [2, 3, [4, 5]], 6, [[7]]];
foreach (flatten($nested) as $v) {
    echo $v, ' ';
}
echo "\n";

// Careful: keys from yield from can repeat
function letters(): Generator
{
    yield from ['a', 'b'];
    yield from ['c', 'd'];
}
print_r(iterator_to_array(letters()));         // keys 0,1,0,1: values overwritten
print_r(iterator_to_array(letters(), false));  // a plain list

yield fromは内側のキーを保つので、どちらの配列もキー0と1をyieldします。そのためiterator_to_array()はaとbを上書きしてしまいます。値だけが重要なときは、2つ目の引数にfalseを渡しましょう。

send()とgetReturn()

ジェネレータは値を受け取ることもできます。$x = yield;で一時停止して待ち、$gen->send($value)はそのyieldの結果を$valueとしてジェネレータを再開します。またジェネレータは最終的な値をreturnでき、終わったあとにgetReturn()で読めます。

<?php
function runningAverage(): Generator
{
    $total = 0;
    $count = 0;
    $average = null;
    while (true) {
        $value = yield $average;   // send() puts a value here
        if ($value === null) {
            return $count;         // final result
        }
        $total += $value;
        $count++;
        $average = $total / $count;
    }
}

$avg = runningAverage();
$avg->current();                   // run to the first yield

foreach ([10, 20, 60] as $n) {
    echo "after $n: ", $avg->send($n), "\n";
}

$avg->send(null);                  // ends the loop
echo "values seen: ", $avg->getReturn(), "\n";

ほとんどのコードではsend()は必要なく、foreachでの遅延読み込みが日常的な使い方です。send()はコルーチンのライブラリを支える基本の部品です。

ジェネレータは1回しかループできない

ジェネレータは前に進むだけで、巻き戻せません。foreachで使い切ったあと、同じオブジェクトをもう一度ループすると例外が投げられます。

<?php
// This throws an Exception on purpose: the generator is already finished
function colors(): Generator
{
    yield 'red';
    yield 'green';
}

$gen = colors();
foreach ($gen as $c) {
    echo $c, "\n";
}
foreach ($gen as $c) {   // second pass
    echo $c, "\n";
}

直すには、ループごとにジェネレータ関数を呼び直す（foreach (colors() as $c)）か、本当に2回必要ならiterator_to_array(colors(), false)で一度だけ値を集めます。それを頻繁にしているなら、そのデータには普通の配列が正しい選択でした。