المولّدات في 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. وتكبر الفجوة مع البيانات. والفكرة نفسها هي ما يجعل المولّدات مفيدة للملفات الكبيرة ونتائج قواعد البيانات وصفحات الواجهات البرمجية: عالج عنصرًا، ثم تخلّص منه، وخذ التالي.

إعطاء المفاتيح والقيم

تضبط 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 هي الاستخدام اليومي. وهي اللبنة التي تقوم عليها مكتبات الروتينات المشتركة.

لا يمكن المرور على المولّد إلا مرة واحدة

تعمل المولّدات إلى الأمام ولا يمكن إرجاعها. فبعد أن تستهلك 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) عندما تحتاج إليها مرتين فعلًا. وإذا وجدت نفسك تفعل ذلك كثيرًا، فالمصفوفة العادية كانت الخيار الصحيح لتلك البيانات.