Generator PHP: yield, yield from, dan Hemat Memori

Generator adalah fungsi yang berisi yield. Memanggilnya tidak menjalankan body-nya; pemanggilan itu mengembalikan object Generator yang bisa ditelusuri dengan foreach. Setiap yield $value menyerahkan satu nilai ke loop dan menjeda fungsi sampai loop meminta nilai berikutnya, jadi nilai dihasilkan satu per satu alih-alih dikumpulkan dulu dalam 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";
}

Output-nya bergantian antara generator dan loop: setiap nilai baru dibuat saat loop memintanya.

Generator menghemat memori

range(1, 1000000) membuat array berisi sejuta integer sebelum loop dimulai. Generator yang meng-yield angka yang sama tidak pernah menyimpan lebih dari satu angka. Jalankan kode ini dan bandingkan memori yang dibutuhkan masing-masing versi:

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

Kedua loop mencetak jumlah yang sama, 500000500000, tetapi versi array melaporkan extra memory 16.0 MB dan generator extra memory 0.0 MB. Selisihnya makin besar seiring bertambahnya data. Ide yang sama inilah yang membuat generator berguna untuk file besar, hasil database, dan halaman API: proses satu item, buang, lalu ambil yang berikutnya.

Yield key dan value

yield $key => $value menentukan key yang diterima oleh foreach ($gen as $key => $value). Tanpa key, generator memberi nomor pada nilainya mulai dari 0, seperti list. Pemakaian yang umum adalah membaca file baris per baris beserta nomor barisnya:

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

Hanya satu baris yang ada di memori setiap saat, jadi fungsi yang sama bisa menangani file log berukuran 2 GB. fopen() dan fgets() membahas fungsi file yang dipakai di sini.

Deret tanpa akhir dan pipeline lazy

Generator bisa berulang selamanya, karena ia hanya berjalan sejauh yang diminta oleh pemakainya. Hentikan dengan break, atau bungkus dengan generator lain yang mengambil beberapa nilai pertama. Merangkai generator-generator kecil menghasilkan pipeline yang setiap langkahnya lazy:

<?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() tidak pernah berhenti dengan sendirinya, tetapi program tetap selesai: take() berhenti meminta setelah jumlah yang diminta tercapai, dan tidak ada nilai lebih dari itu yang pernah dihitung.

yield from: mendelegasikan ke generator lain

yield from meneruskan setiap nilai dari array, iterator, atau generator lain. Dengan cara inilah kamu memecah generator menjadi generator yang lebih kecil, atau menelusuri struktur bersarang secara rekursif:

<?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 mempertahankan key dari dalam, jadi kedua array meng-yield key 0 dan 1. iterator_to_array() kemudian menimpa a dan b. Berikan false sebagai argumen kedua setiap kali yang penting hanya nilainya.

send() dan getReturn()

Generator juga bisa menerima nilai. $x = yield; menjeda dan menunggu; $gen->send($value) melanjutkan generator dengan $value sebagai hasil dari yield itu. Generator juga bisa melakukan return dengan nilai akhir, yang kamu baca dengan getReturn() setelah generator selesai.

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

Sebagian besar kode tidak pernah butuh send(); membaca secara lazy dengan foreach adalah pemakaian sehari-hari. Fitur ini adalah fondasi di balik library coroutine.

Generator hanya bisa ditelusuri sekali

Generator berjalan maju dan tidak bisa diulang dari awal. Setelah sebuah foreach menghabiskannya, loop kedua atas object yang sama akan melempar exception:

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

Solusinya adalah memanggil lagi fungsi generator-nya untuk setiap putaran, foreach (colors() as $c), atau mengumpulkan nilainya sekali dengan iterator_to_array(colors(), false) saat kamu benar-benar membutuhkannya dua kali. Jika kamu sering melakukannya, berarti array biasa adalah pilihan yang tepat untuk data itu.