Performa: penganalisis fragmentasi memori

Sekilas pandang

Modul Performance memiliki cakupan yang sempit. Modul ini menyediakan satu alat observasi khusus, MemoryFragmentationAnalyzer, yang mengukur memori puncak dan memori yang tertahan selama jendela kerja mesin yang ditandai. Permukaan publiknya juga mencakup snapshot yang tidak berubah yang dihasilkan oleh alat ini. Modul ini tidak menegakkan anggaran, tidak membatasi laju kerja, dan tidak mengubah perilaku mesin.

Cakupan dan stabilitas. Permukaan aktual modul ini adalah dua kelas (MemoryFragmentationAnalyzer, MemoryFragmentationSnapshot). Modul ini bukan harness penegakan anggaran per operasi. Nilai performance_budget di frontmatter setiap modul adalah konvensi dokumentasi, bukan nilai yang ditegakkan oleh modul ini. Permukaannya bersifat experimental: ini adalah diagnostik yang diperkenalkan pada @since 3.2.0. Bentuk snapshot-nya dapat berkembang.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Pemanfaatan sumber daya adalah aspek kualitas utama bagi mesin Portable Document Format (PDF). Hal minimum yang dapat diamati adalah pemisahan antara memori puncak (titik tertinggi selama sebuah jendela) dan memori tertahan (yang masih ditahan setelah jendela berakhir). Modul ini hanya mengukur hal tersebut.

MemoryFragmentationAnalyzer hanya mengamati; modul ini tidak mengubah keadaan writer maupun dokumen. reset() menjalankan satu siklus garbage collection (GC) dan mereset penghitung puncak PHP sehingga pengukuran berikutnya berada dalam jendela sejak reset tersebut. mark(string $label) menangkap satu MemoryFragmentationSnapshot pada satu titik berlabel. snapshots() mengembalikan snapshot yang telah ditangkap. peakDelta() dan retainedDelta() melaporkan perubahan memori puncak dan memori tertahan selama eksekusi.

MemoryFragmentationSnapshot adalah objek nilai final readonly: satu titik berlabel dengan transientBytes() (puncak dikurangi tertahan, yaitu memori yang digunakan lalu dilepaskan), retentionRatio() (tertahan dibagi puncak), dan toArray() untuk ekspor. Nilai transient-bytes yang tinggi dengan rasio retensi yang rendah menandakan churn yang dapat dihilangkan melalui strategi penggunaan ulang buffer. Kedua kelas tersebut adalah @since 3.2.0.

Permukaan API

Kelas	Anggota utama	Peran
MemoryFragmentationAnalyzer	reset(), mark(string $label), snapshots(), peakDelta(), retainedDelta()	Penganalisis memori khusus observasi (@since 3.2.0)
MemoryFragmentationSnapshot	transientBytes(), retentionRatio(), toArray()	Pengukuran berlabel yang tak berubah (@since 3.2.0)

Jalankan composer docs:generate-api-php -- --module=Performance untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Pasang instrumentasi pada satu jalur panas, lalu baca delta-nya.

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

Contoh kode — Produksi

Bungkus proses render dan kirimkan snapshot fragmentasi ke sink metrik. Perlakukan rasio retensi yang rendah saat transient bytes tinggi sebagai sinyal churn.

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

Kasus tepi & jebakan

• reset() memanggil gc_collect_cycles() dan memory_reset_peak_usage(). Hal ini memengaruhi penghitung puncak PHP secara global pada proses. Jangan menjalankannya secara berselang-seling dengan komponen lain yang membaca penghitung yang sama dalam request yang sama.
• Pengukuran berada dalam jendela sejak reset() terakhir. Pemanggilan mark() tanpa didahului reset() mengukur sejak proses dimulai, yang biasanya bukan yang Anda inginkan.
• Ini adalah diagnostik, bukan kontrol. Modul ini tidak pernah membatasi laju atau membatalkan kerja. Jangan membangun back pressure berdasarkan modul ini.
• Profil reproduksibilitasnya bersifat structural: angka byte bergantung pada runtime, allocator, dan keadaan GC. Dua eksekusi dapat berbeda secara numerik bahkan untuk kerja logis yang sama.

Performa

Overhead dari penganalisis itu sendiri adalah satu siklus garbage collection pada reset() dan satu pembacaan hrtime() / memory_get_* per mark(), yang dapat diabaikan dibandingkan pekerjaan yang diamati. Modul ini mengalokasikan satu snapshot kecil per mark(). Nilai performance_budget dalam frontmatter ini adalah angka rujukan untuk seluruh dokumentasi; modul ini tidak menegakkannya.

Catatan keamanan

Nilai memori adalah data diagnostik. Nilai tersebut tidak memuat konten dokumen, tetapi profil memori yang terperinci dapat mengungkap ukuran dan bentuk masukan. Perlakukan ekspor snapshot sebagai telemetri internal, dan terapkan kewajiban pembersihan log proyek sebelum Anda membagikannya secara eksternal. Modul ini tidak melakukan input/output (I/O) dan tidak menyematkan data eksternal. Lihat model ancaman mesin di /modules/core/security/.

Kesesuaian

Modul ini tidak membuat klaim normatif apa pun tentang spesifikasi PDF. Ini adalah diagnostik memori dan tidak mengimplementasikan protokol terstandar mana pun yang memiliki klausa untuk dikutip. Rasional arsitekturnya merujuk pada sudut pandang kualitas pemanfaatan sumber daya dari kerangka deskripsi arsitektur ISO/IEC/IEEE 42010. Rujukan tersebut adalah penyelarasan dengan praktik arsitektur, bukan kutipan PDF. Kesesuaian mesin divalidasi oleh suite oracle dan golden yang dijelaskan di /modules/core/conformance/.

Lihat juga

• Modul Observability — permukaan status runtime yang lebih luas.
• Modul Telemetry — mengirimkan metrik ke backend eksternal.
• Modul Writer — subjek yang memorinya umum diamati.
• Model keamanan mesin