Generatory w PHP: yield, yield from i zużycie pamięci

Generator to funkcja zawierająca yield. Jej wywołanie nie wykonuje treści; zwraca obiekt Generator, po którym foreach może przejść pętlą. Każde yield $value przekazuje pętli jedną wartość i wstrzymuje funkcję, dopóki pętla nie poprosi o następną, więc wartości powstają po jednej, a nie są najpierw zbierane w tablicy.

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

Wynik przeplata generator i pętlę: każda wartość powstaje dopiero wtedy, gdy pętla o nią poprosi.

Generatory oszczędzają pamięć

range(1, 1000000) buduje tablicę miliona liczb całkowitych, zanim pętla się zacznie. Generator zwracający te same liczby nigdy nie trzyma więcej niż jednej z nich. Uruchom to i porównaj pamięć potrzebną każdej wersji:

<?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);

Obie pętle wypisują tę samą sumę, 500000500000, ale wersja z tablicą zgłasza extra memory 16.0 MB, a generator extra memory 0.0 MB. Różnica rośnie wraz z danymi. Ta sama idea sprawia, że generatory przydają się przy dużych plikach, wynikach z bazy danych i stronach API: przetwórz jeden element, porzuć go, weź następny.

Klucze i wartości w yield

yield $key => $value ustawia klucz, który dostaje foreach ($gen as $key => $value). Bez klucza generator numeruje wartości od 0, jak listę. Częste zastosowanie to czytanie pliku linia po linii z numerami linii:

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

W pamięci jest naraz tylko jedna linia, więc ta sama funkcja obsłuży plik logu o rozmiarze 2 GB. Użyte tu funkcje plikowe opisuje strona fopen() i fgets().

Ciągi nieskończone i leniwe potoki

Generator może działać w nieskończonej pętli, bo wykonuje się tylko tak daleko, jak prosi konsument. Zatrzymaj go przez break albo otocz innym generatorem, który bierze kilka pierwszych wartości. Łączenie małych generatorów daje potok, w którym każdy krok jest leniwy:

<?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() sam nigdy się nie kończy, a jednak program się kończy: take() przestaje prosić po żądanej liczbie wartości i nic poza tym nigdy nie jest obliczane.

yield from: przekazanie do innego generatora

yield from przepuszcza każdą wartość tablicy, iteratora albo innego generatora. Tak dzielisz generator na mniejsze albo rekurencyjnie przechodzisz zagnieżdżoną strukturę:

<?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 zachowuje wewnętrzne klucze, więc obie tablice zwracają klucze 0 i 1. iterator_to_array() nadpisuje wtedy a i b. Przekaż false jako drugi argument zawsze, gdy liczą się tylko wartości.

send() i getReturn()

Generator może też przyjmować wartości. $x = yield; wstrzymuje i czeka; $gen->send($value) wznawia generator z $value jako wynikiem tego yield. Generator może też przez return zwrócić wartość końcową, którą odczytasz przez getReturn() po jego zakończeniu.

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

Większość kodu nigdy nie potrzebuje send(); codzienne zastosowanie to leniwe czytanie przez foreach. To element, na którym opierają się biblioteki korutyn.

Po generatorze można przejść tylko raz

Generatory działają do przodu i nie da się ich przewinąć. Gdy foreach zużyje jeden, druga pętla po tym samym obiekcie rzuca wyjątek:

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

Rozwiązanie to wywołanie funkcji generatora od nowa przy każdym przejściu, foreach (colors() as $c), albo jednorazowe zebranie wartości przez iterator_to_array(colors(), false), gdy naprawdę potrzebujesz ich dwa razy. Jeśli robisz to często, dla tych danych właściwym wyborem była zwykła tablica.