Generatori in PHP: yield, yield from e uso della memoria

Un generatore è una funzione che contiene yield. Chiamarla non esegue il corpo; restituisce un oggetto Generator che foreach può scorrere. Ogni yield $value passa un valore al ciclo e mette in pausa la funzione finché il ciclo non chiede il successivo, quindi i valori vengono prodotti uno alla volta invece di essere prima raccolti in un array.

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

L'output si alterna tra il generatore e il ciclo: ogni valore viene creato solo quando il ciclo lo chiede.

I generatori risparmiano memoria

range(1, 1000000) costruisce un array di un milione di interi prima che il ciclo parta. Un generatore che produce gli stessi numeri non ne tiene mai più di uno. Eseguilo e confronta la memoria che serve a ciascuna versione:

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

Entrambi i cicli stampano la stessa somma, 500000500000, ma la versione con l'array riporta extra memory 16.0 MB e il generatore extra memory 0.0 MB. Il divario cresce con i dati. È la stessa idea che rende utili i generatori per file grandi, risultati di database e pagine di API: elabora un elemento, lascialo andare, prendi il successivo.

Chiavi e valori con yield

yield $key => $value imposta la chiave che riceve foreach ($gen as $key => $value). Senza chiave, un generatore numera i suoi valori da 0, come una lista. Un uso comune è leggere un file riga per riga con i numeri di riga:

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

In memoria c'è una sola riga alla volta, quindi la stessa funzione gestisce un file di log da 2 GB. fopen() e fgets() trattano le funzioni sui file usate qui.

Sequenze infinite e pipeline pigre

Un generatore può ciclare all'infinito, perché va avanti solo quanto chiede chi lo consuma. Fermati con break, oppure racchiudilo in un altro generatore che prende i primi valori. Concatenare piccoli generatori dà una pipeline in cui ogni passo è pigro:

<?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() non termina mai da sola, eppure il programma finisce: take() smette di chiedere dopo il numero richiesto, e nulla oltre viene mai calcolato.

yield from: delegare a un altro generatore

yield from inoltra ogni valore di un array, di un iteratore o di un altro generatore. È così che dividi un generatore in generatori più piccoli, o percorri ricorsivamente una struttura annidata:

<?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 mantiene le chiavi interne, quindi entrambi gli array producono le chiavi 0 e 1. iterator_to_array() sovrascrive allora a e b. Passa false come secondo argomento ogni volta che contano solo i valori.

send() e getReturn()

Un generatore può anche ricevere valori. $x = yield; si mette in pausa e aspetta; $gen->send($value) riprende il generatore con $value come risultato di quello yield. E un generatore può fare return di un valore finale, che leggi con getReturn() quando ha finito.

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

La maggior parte del codice non ha mai bisogno di send(); leggere in modo pigro con foreach è l'uso di tutti i giorni. È il mattone alla base delle librerie di coroutine.

Un generatore si può scorrere una volta sola

I generatori vanno in avanti e non si possono riavvolgere. Una volta che un foreach ne ha consumato uno, un secondo ciclo sullo stesso oggetto lancia un'eccezione:

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

La soluzione è chiamare di nuovo la funzione generatrice per ogni passaggio, foreach (colors() as $c), oppure raccogliere i valori una volta con iterator_to_array(colors(), false) quando ti servono davvero due volte. Se ti ritrovi a farlo spesso, per quei dati la scelta giusta era un semplice array.