Performans: bellek parçalanması çözümleyicisi

Bir bakışta

Performance modülünün kapsamı dardır. İşaretlenen motor çalışma pencerelerinde en yüksek ve tutulan belleği ölçen, yalnızca gözleme yönelik tek bir araç sağlar: MemoryFragmentationAnalyzer. Genel arabirimi, aracın ürettiği değişmez anlık görüntüyü de içerir. Bütçe dayatmaz, çalışmayı kısıtlamaz ve motor davranışını değiştirmez.

Kapsam ve kararlılık. Bu modülün gerçek arabirimi iki sınıftan oluşur (MemoryFragmentationAnalyzer, MemoryFragmentationSnapshot). Bu, işlem başına bütçe dayatma düzeneği değildir. Her modülün ön bilgisinde yer alan performance_budget değeri bir belgeleme kuralıdır; bu modülün dayattığı bir değer değildir. Bu arabirim experimental durumdadır: bir tanılama aracıdır ve @since 3.2.0 sürümünde kullanıma sunulmuştur. Anlık görüntü biçimi değişebilir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Kaynak kullanımı, bir Taşınabilir Belge Biçimi (PDF) motoru için birincil önemde bir kalite konusudur. Burada gözlemlenen en temel ayrım, en yüksek bellek (bir pencere boyunca ulaşılan üst sınır) ile tutulan bellek (pencereden sonra hâlâ elde tutulan miktar) arasındadır. Bu modül yalnızca bunu ölçer.

MemoryFragmentationAnalyzer yalnızca gözlem yapar; yazıcıyı veya belge durumunu değiştirmez. reset() bir çöp toplama (GC) döngüsü çalıştırır ve PHP’nin en yüksek sayacını sıfırlar; böylece sonraki ölçümler sıfırlamadan bu yana geçen pencereye ait olur. mark(string $label) etiketlenen bir noktada bir MemoryFragmentationSnapshot yakalar. snapshots() yakalanan anlık görüntüler dizisini döndürür. peakDelta() ve retainedDelta() çalışma boyunca en yüksek ve tutulan bellek değişimini raporlar.

MemoryFragmentationSnapshot bir final readonly değer nesnesidir: etiketlenen bir noktayı temsil eder ve şunları içerir: transientBytes() (en yüksek eksi tutulan, yani kullanılıp serbest bırakılan bellek), retentionRatio() (tutulanın en yükseğe oranı) ve dışa aktarma için toArray(). Düşük tutma oranıyla birlikte yüksek bir geçici bayt değeri, arabellek yeniden kullanım stratejisiyle giderilebilecek gereksiz devinime işaret eder. Her iki sınıf da @since 3.2.0 kapsamındadır.

API arabirimi

Sınıf	Başlıca üyeler	Rol
MemoryFragmentationAnalyzer	reset(), mark(string $label), snapshots(), peakDelta(), retainedDelta()	Yalnızca gözleme yönelik bellek çözümleyicisi (@since 3.2.0)
MemoryFragmentationSnapshot	transientBytes(), retentionRatio(), toArray()	Değişmez etiketlenmiş ölçüm (@since 3.2.0)

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Performance komutunu çalıştırın.

Kod örneği — Hızlı başlangıç

Sıcak bir yolu gözlemleyin, ardından değişim değerlerini okuyun.

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

Kod örneği — Üretim

Bir işleme çalışmasını sarmalayın ve parçalanma anlık görüntüsünü bir ölçüm havuzuna gönderin. Geçici baytlar yüksekken tutma oranının düşük olmasını gereksiz devinim işareti olarak değerlendirin.

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

Uç durumlar ve dikkat edilecek noktalar

• reset(), gc_collect_cycles() ve memory_reset_peak_usage() işlevlerini çağırır. PHP’nin en yüksek sayacını işlem genelinde etkiler. Aynı istek içinde aynı sayacı okuyan başka bir bileşenle iç içe kullanmayın.
• Ölçümler, son reset() çağrısından bu yana geçen pencereye aittir. Bir mark(), öncesinde bir reset() bulunmadan işlem başlangıcından itibaren ölçer; bu da genellikle istediğiniz şey değildir.
• Bu bir tanılama aracıdır, bir denetim aracı değildir. Çalışmayı asla kısıtlamaz veya durdurmaz. Bunun üzerine geri basınç mekanizması kurmayın.
• Yeniden üretilebilirlik profili structural olarak sınıflandırılır: bayt değerleri çalışma zamanına, ayırıcıya ve GC durumuna bağlıdır. Aynı mantıksal çalışma için bile iki çalıştırmanın sayısal sonuçları farklı olabilir.

Performans

Çözümleyicinin kendi ek yükü, reset() sırasında çalışan bir çöp toplama döngüsü ve hrtime() / memory_get_* için her mark() başına bir kez yapılan okumayla sınırlıdır; bu da gözlemlediği çalışmaya göre ihmal edilebilir düzeydedir. Her mark() başına küçük bir anlık görüntü nesnesi ayırır. Bu ön bilgide yer alan performance_budget değeri, belgeler genelindeki başvuru değeridir; bu modül bu değeri dayatmaz.

Güvenlik notları

Bellek değerleri tanılama verileridir. Belge içeriği içermezler, ancak ayrıntılı bir bellek profili girdi boyutunu ve yapısını açığa çıkarabilir. Anlık görüntü dışa aktarımlarını dahili telemetri olarak değerlendirin ve dışarıyla paylaşmadan önce projenin günlük temizleme gereksinimlerini uygulayın. Modül hiçbir input/output (G/Ç) işlemi yapmaz ve hiçbir dış veri gömmez. Motorun tehdit modeli için /modules/core/security/ bölümüne bakın.

Uyumluluk

Bu modül, PDF belirtimi hakkında hiçbir bağlayıcı iddiada bulunmaz. Bir bellek tanılama aracıdır ve atıf yapılabilecek maddeleri olan standartlaştırılmış bir protokol uygulamaz. Mimari gerekçesi, ISO/IEC/IEEE 42010 mimari tanım çerçevesindeki kaynak kullanımı kalite görünümüne atıfta bulunur. Bu atıf bir mimari uygulama uyumudur, bir PDF atfı değildir. Motor uyumluluğu, /modules/core/conformance/ bölümünde açıklanan oracle ve golden takımlarıyla doğrulanır.

Ayrıca bakınız

• Observability modülü — daha geniş çalışma zamanı durumu arabirimi.
• Telemetry modülü — dış bir arka uca ölçümler gönderir.
• Writer modülü — bellek gözleminde sık izlenen bir öğe.
• Motor güvenlik modeli