Генераторы PHP: yield, yield from и экономия памяти

Генератор это функция, в которой есть yield. Её вызов не выполняет тело; он возвращает объект Generator, который можно обойти через foreach. Каждый yield $value отдаёт одно значение циклу и приостанавливает функцию, пока цикл не попросит следующее, поэтому значения создаются по одному, а не собираются сначала в массив.

<?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) строит массив из миллиона целых чисел ещё до начала цикла. Генератор, который выдаёт те же числа, никогда не держит больше одного. Запустите и сравните, сколько памяти нужно каждому варианту:

<?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: обработать один элемент, выбросить его, взять следующий.

Ключи и значения в yield

yield $key => $value задаёт ключ, который получает foreach ($gen as $key => $value). Без ключа генератор нумерует значения с 0, как список. Частое применение это чтение файла построчно с номерами строк:

<?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";
    }
}

В памяти одновременно только одна строка, поэтому та же функция справится и с лог-файлом на 2 ГБ. Используемые здесь функции для работы с файлами описаны в 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. Затем iterator_to_array() перезаписывает a и b. Передавайте 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() построены библиотеки корутин.

Генератор можно обойти только один раз

Генераторы работают только вперёд и не перематываются. Когда 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), или один раз собрать значения через iterator_to_array(colors(), false), когда они действительно нужны дважды. Если вы делаете так часто, для этих данных правильным выбором был обычный массив.