גנרטורים ב-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 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. iterator_to_array() דורסת אז את a ואת b. העבירו false כארגומנט השני בכל פעם שרק הערכים חשובים.

send() ו-getReturn()

גנרטור יכול גם לקבל ערכים. $x = yield; משהה ומחכה; $gen->send($value) ממשיך את הגנרטור כש-$value היא התוצאה של אותו yield. וגנרטור יכול לעשות 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 היא השימוש היומיומי. זו אבן הבניין שמאחורי ספריות של coroutines.

אפשר לעבור על גנרטור פעם אחת בלבד

גנרטורים רצים קדימה ואי אפשר להחזיר אותם להתחלה. ברגע ש-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) כשאתם באמת צריכים אותם פעמיים. אם אתם מוצאים את עצמכם עושים את זה לעיתים קרובות, מערך רגיל היה הבחירה הנכונה לנתונים האלה.