الأداء: محلل تجزؤ الذاكرة

لمحة سريعة

نطاق وحدة الأداء ضيق. فهي توفِّر أداة مراقبة واحدة فقط، MemoryFragmentationAnalyzer، تقيس ذروة الذاكرة والذاكرة المحتجزة عبر نوافذ معلَّمة من عمل المحرك. وتتضمن واجهتها العامة أيضًا اللقطة غير القابلة للتغيير التي تنتجها الأداة. لا تفرض ميزانيات، ولا تقيِّد العمل، ولا تغيِّر سلوك المحرك.

النطاق والاستقرار. الواجهة الفعلية لهذه الوحدة هي فئتان (MemoryFragmentationAnalyzer، MemoryFragmentationSnapshot). إنها ليست إطار عمل لفرض الميزانية لكل عملية. قيمة performance_budget في الواجهة الأمامية لكل وحدة هي اصطلاح توثيقي، وليست قيمةً تفرضها هذه الوحدة. الواجهة experimental: فهي أداة تشخيصية أُدخلت في @since 3.2.0. وقد يتطور شكل اللقطة التي تنتجها.

التثبيت

composer require nextpdf/core:^3

نظرة عامة مفاهيمية

استخدام الموارد شاغل جودة من الدرجة الأولى لمحرك تنسيق المستندات المحمولة (⁨PDF⁩). والحد الأدنى مما ينبغي رصده هو الفصل بين الذاكرة القصوى (أعلى مستوى تبلغه خلال نافذة ما) والذاكرة المحتجزة (ما يظل محتجَزًا بعد النافذة). هذه الوحدة تقيس ذلك فقط.

MemoryFragmentationAnalyzer يراقب فقط؛ فهو لا يغيِّر حالة الكاتب أو المستند. reset() تشغِّل دورة جمع مهملات (⁨GC⁩) وتعيد ضبط عدّاد الذروة في ⁨PHP⁩، بحيث تُنسب القياسات اللاحقة إلى النافذة التي تبدأ بعد إعادة الضبط. mark(string $label) تلتقط MemoryFragmentationSnapshot عند نقطة معلَّمة. snapshots() تُعيد السلسلة الملتقَطة. peakDelta() وretainedDelta() تُبلِغان عن التغيّر في الذروة والمحتجَز عبر التشغيل.

MemoryFragmentationSnapshot هو كائن قيمة final readonly: نقطة معلَّمة تتضمن transientBytes() (الذروة ناقص المحتجَز، أي الذاكرة التي استُخدمت ثم حُرِّرت)، وretentionRatio() (المحتجَز نسبةً إلى الذروة)، وtoArray() للتصدير. وتشير القيمة المرتفعة للبايتات العابرة مع نسبة احتجاز منخفضة إلى تموّج يمكن لاستراتيجية إعادة استخدام المخزن المؤقت أن تزيله. كلتا الفئتين @since 3.2.0.

واجهة ⁨API⁩

الفئة	الأعضاء الرئيسية	الدور
`MemoryFragmentationAnalyzer`	`reset()`، `mark(string $label)`، `snapshots()`، `peakDelta()`، `retainedDelta()`	محلِّل ذاكرة للمراقبة فقط ‏(`@since 3.2.0`)
`MemoryFragmentationSnapshot`	`transientBytes()`، `retentionRatio()`، `toArray()`	قياس معلَّم غير قابل للتغيير ‏(`@since 3.2.0`)

شغِّل composer docs:generate-api-php -- --module=Performance لتوليد جدول ⁨PHPDoc⁩ الكامل.

مثال برمجي — بداية سريعة

أضف أدوات القياس إلى مسار ساخن، ثم اقرأ الفروق.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Performance\MemoryFragmentationAnalyzer;

$analyzer = new MemoryFragmentationAnalyzer();
$analyzer->reset();

$analyzer->mark('before-write');
// ... engine work under observation ...
$analyzer->mark('after-write');

printf("Peak delta: %d B, retained delta: %d B\n", $analyzer->peakDelta(), $analyzer->retainedDelta());

مثال برمجي — للإنتاج

غلِّف عملية العرض وأرسل لقطة التجزؤ إلى مستودع مقاييس. عامِل نسبة الاحتجاز المنخفضة مع البايتات العابرة المرتفعة على أنها إشارة تموّج.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Performance\MemoryFragmentationAnalyzer;
use Psr\Log\LoggerInterface;

final readonly class RenderMemoryProbe
{
    public function __construct(private LoggerInterface $logger) {}

    /** @param callable():void $render The render closure to observe. */
    public function observe(callable $render): void
    {
        $analyzer = new MemoryFragmentationAnalyzer();
        $analyzer->reset();

        $analyzer->mark('start');
        $render();
        $analyzer->mark('end');

        foreach ($analyzer->snapshots() as $snapshot) {
            $this->logger->info('mem-frag', $snapshot->toArray());
        }
    }
}

الحالات الحدّية والمزالق

reset() تستدعي gc_collect_cycles() وmemory_reset_peak_usage(). ولها أثر شامل على مستوى العملية في عدّاد الذروة في ⁨PHP.⁩ لا تشابكها مع مكوِّن آخر يقرأ العدّاد نفسه ضمن الطلب نفسه.
تنتمي القياسات إلى النافذة منذ آخر reset(). إنّ استدعاء mark() دون reset() سابق يقيس من بداية العملية، وهذا ليس ما تريده عادةً.
هذه أداة تشخيصية، وليست أداة تحكم. لا تقيِّد العمل ولا توقفه أبدًا. لا تبنِ عليها آلية ضغط عكسي.
سمة قابلية إعادة الإنتاج هي structural: تعتمد أرقام البايتات على وقت التشغيل والمُخصِّص وحالة ⁨GC.⁩ وقد يختلف تشغيلان رقميًّا حتى للعمل المنطقي نفسه.

الأداء

يتمثل العبء الإضافي للمحلل نفسه في دورة جمع مهملات عند reset() وقراءة واحدة من hrtime() / memory_get_* لكل mark()، وهو عبء لا يُذكر مقارنةً بالعمل الذي تراقبه. تُخصَّص لقطة صغيرة واحدة لكل mark(). قيمة performance_budget في هذه الواجهة الأمامية رقم مرجعي على مستوى التوثيق؛ ولا تفرضه هذه الوحدة.

ملاحظات أمنية

أرقام الذاكرة بيانات تشخيصية. لا تحتوي على محتوى المستند، لكن بصمة ذاكرة دقيقة التفاصيل قد تكشف حجم المُدخل وشكله. عامِل صادرات اللقطات على أنها قياسات داخلية، وطبِّق التزام المشروع بتنقية السجلات قبل مشاركتها خارجيًّا. لا تُجري الوحدة أي ⁨input/output⁩ ‏(⁨I/O⁩) ولا تُضمِّن أي بيانات خارجية. راجع نموذج تهديد المحرك في /modules/core/security/.

المطابقة

لا تقدِّم هذه الوحدة أي ادعاء معياري بشأن مواصفة ⁨PDF.⁩ إنها أداة تشخيص للذاكرة، ولا تُنفِّذ أي بروتوكول معياري ببنود يمكن الاستشهاد بها. يشير أساسها المعماري إلى منظور جودة استخدام الموارد من إطار وصف المعمارية ⁨ISO/IEC/IEEE 42010.⁩ هذا المرجع محاذاة لممارسة معمارية، وليس استشهادًا بمواصفة ⁨PDF.⁩ يُتحقَّق من مطابقة المحرك عبر مجموعات الأوراكل والمجموعات الذهبية الموصوفة في /modules/core/conformance/.

انظر أيضًا

وحدة قابلية المراقبة — واجهة أوسع لحالة وقت التشغيل.
وحدة القياس عن بُعد — تُصدِر المقاييس إلى واجهة خلفية خارجية.
وحدة الكاتب — موضوع شائع لمراقبة الذاكرة.
نموذج أمان المحرك