Yüksek hacimli belge üretimi

Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 Spec Spec: ISO 9241-112:2025, §6.1.2.3 ISO 9241-112:2025 §6.1.2.3 Evidence ≡ Benchmark-backed Evidence: Benchmark-backed

Bir bakışta

Tek bir PDF oluşturmak bir işlev çağrısıdır. Yüz bin tanesini belirli bir zamanlamayla oluşturmak ise bir sistem sorunudur: sınırlı kalması gereken bellek, paralel yürütülmesi gereken işler ve anlamlı olması gereken sayılar. Bu sayfa, toplu üretim senaryosunu veri çıkışı sorusundan başlayarak dayanıklı bir dağıtım yapısına kadar adım adım ele alır. Dürüst cevabın bir manşet rakamı değil, “kendi belgelerinizde ölçün” olduğunu açıkça belirtir.

Bunun önemi nedir

Toplu üretim iki tipik biçimde başarısız olur. Birincisi, belleğin yavaş yavaş artmasıdır. Uzun ömürlü bir çalışan, belge başına tutulan durumu biriktirir ve sonunda toplu işin ortasında sonlandırılır; bu durumda çalıştırma ne tamamlanmış ne de düzgün biçimde başarısız olmuş olur. İkincisi, kendinden emin ama anlamsız bir sayıdır: basit bir belgeden alınan kıyaslama sonucu, karmaşık belgeleri işleyen bir filoyu boyutlandırmak için kullanılır ve bunun yanlış olduğu yalnızca üretim yükü altında ortaya çıkar.

Her ikisinden de kaçınabilirsiniz; ancak bunun için bellek yapısını ve ölçüm yöntemini ilk olaydan sonra eklemek yerine baştan tasarlamanız gerekir.

Kısaca

• İş birimi, paylaşılan bir belge değil, tek kullanımlık bir belgedir. Süreç ömrü boyunca yaşayan verileri (yazı tipleri, görüntü önbelleği) paylaşılan kayıt defterlerinde tutun; belgeyi her işleme için oluşturup atın.
• Belleğin iki parçası vardır ve uzun ömürlü bir çalışan için yalnızca biri önemlidir. İşleme sırasında görülen geçici tepe değer beklenen bir durumdur; geri dönmeyen tutulan bellek ise toplu işi sonlandıran sızıntıdır.
• Veri çıkışı, paralellik ile işleme başına sınırlı maliyetin toplamıdır. Dayanıklı yapı, her işi işleyip serbest bırakan durumsuz çalışanları besleyen bir kuyruktur.
• Yöntemi olmayan bir sayı, sayı değildir. NextPDF, işleme başına ölçümleri sizin topladığınız veriler olarak raporlar ve niteliksiz hız iddialarını reddeder. En önemli rakam, kendi şablonlarınızda ölçtüğünüz rakamdır (ISO 24495-1 §5.x11 — önemli mesajı, okuyucunun bulacağı yere koyun).

NextPDF buna nasıl yaklaşır

Mimari, tek bir karar üzerine kuruludur: süreç boyunca yaşayan durum paylaşılır ve değişmezdir; bir işleme boyunca yaşayan durum ise yenidir ve atılır. Yazı tipleri, bir kez ayrıştırılıp ardından kilitlenen yapısal verilerdir; böylece hiçbir işleme onları değiştirip bir sonrakini bozamaz. Görüntü önbelleği, hiçbir zaman kilitlenmeyen, sınırlı bir en az kullanılan (LRU) depodur; böylece bellek, istekler arasında sızmadan sınırlı kalır. Belge fabrikası durumsuz bir tekildir (singleton); oluşturduğu her belge tek kullanımlıktır.

Bir çalışanın Octane, RoadRunner veya Swoole altında saatlerce güvenle çalışmasını sağlayan şey bu ayrımdır. Belgenin kendini sıfırlamasını ummak yerine, “N isteği N+1 isteğini bozar” şeklindeki başarısızlık biçimini tasarımı gereği ortadan kaldırır.

Senaryonun dört aşaması vardır.

1. Warm the shared state once On worker boot, parse and lock the font registry and size the image cache. This cost is paid once, not per document.
2. Enqueue the work A queue holds the render jobs. The queue is the throughput dial — workers scale horizontally behind it.
3. Render on a disposable document Each worker creates a fresh document from the factory, renders, emits the bytes, and lets the document go.
4. Measure, then size Collect per-render time and peak memory. Size the fleet from measurements on your own templates, not a generic figure.

Yüksek hacimli senaryo uçtan uca: paylaşılan değişmez durum bir kez ısıtılır; her iş tek kullanımlık bir belge üzerinde işlenir ve serbest bırakılır; veri çıkışı, bir çalışanı büyüterek değil, çalışan ekleyerek ölçeklenir.

Çerçeve köprüleri, bu yapıyı sizin elle birleştirmeniz gereken bir şey olmaktan çıkarıp varsayılan hâline getirir. Laravel hizmet sağlayıcısı, yazı tipi kayıt defterini ısıtılmış ve kilitli bir tekil (singleton) olarak kaydeder ve belgeyi her çözümleme için yeni bir örnek olarak bağlar. Sınırlı deneme sayısı, zaman aşımı ve üstel geri çekilme içeren kuyruğa alınmış bir iş ile birlikte gelir. Bu iş, çıktı yolunu çalışan tarafında doğrular, çünkü serileştirilmiş bir kuyruk yükü aktarım sırasında değiştirilebilir. Symfony ve CodeIgniter tümleştirmeleri de aynı tek kullanımlık belge ve paylaşılan kayıt defteri disiplinini izler.

Human-factors note: Human-factors note

Dürüst bir çerçeve, hızlı bir çerçeveden daha önemlidir. Tek bir veri çıkışı sayısı NextPDF için yoktur, çünkü işleme maliyetinde belge belirleyicidir — sayfa sayısı, yazı tipleri, görüntüler ve HTML yerleşiminin söz konusu olup olmaması. Tek sayfalık bir metin belgesinin kıyaslaması, gömülü grafikler içeren elli sayfalık bir rapor hakkında size neredeyse hiçbir şey söylemez. Motor, kendi iş yükünüzü ölçmeniz için size gerekli araçları sağlar. Bir filoyu başkasının belgesine göre boyutlandırmak, bu bölümün önlemek için var olduğu hatadır.

Kanıtların söylediği

Bellek modeli kod desteklidir. Evidence { } Code-backed Evidence: Code-backed Laravel NextPdfServiceProvider, FontRegistry’yi ısıtılıp ardından lock() ile kilitlenen bir tekil olarak, ImageRegistry’yi bilinçli olarak kilitlenmeyen sınırlı LRU bir tekil olarak ve Document’i durumsuz bir fabrika aracılığıyla her çözümleme için bir bağlama olarak kaydeder. Tek kullanımlık belge modeli, metinde değil, kablajın (wiring) içindedir. GeneratePdfJob; tries, timeout ve backoff değerlerini taşır ve çıktı yolunu handle() içinde yeniden doğrular.

Ölçüm yüzeyi kıyaslama desteklidir. Evidence ≡ Benchmark-backed Evidence: Benchmark-backed Motor, her oluşturma için değişmez bir RenderReport yayar; bu rapor işleme süresini milisaniye, tepe belleği bayt, sayfa sayısı, uyarı sayıları ve geri dönüş oluşumları olarak taşır — bir filoyu boyutlandırmak için gereken girdilerin tamamı bunlardır. Ayrı bir bellek parçalanması çözümleyicisi, tepe (geçici) belleği tutulan bellekten ayırt eder. Bu ayrım, uzun ömürlü bir çalışanın sağlıklı mı olduğunu yoksa yavaşça sızıntı mı yaptığını gösterir. Kıyaslama çatısının kendisi, ısınma ile yinelenen turlar için yapılandırılmıştır, çünkü tek bir zamanlama gürültüdür.

Bu disiplin, bir tasarım ilkesidir: Evidence ◇ Design principle Evidence: Design principle NextPDF, performansı yöntemiyle birlikte raporlar ve niteliksiz hız iddialarını reddeder. Bu, bu belgelerin yazılış biçimiyle tutarlıdır — Spec Spec: ISO 24495-1:2023, §5 ISO 24495-1:2023 §5 önemli olan mesajı, okuyucunun bulacağı yere yerleştirir. Burada önemli mesaj ise “kendi iş yükünüzü ölçün” mesajıdır.

Pratik örnek

Aşağıdaki kod, ölçümlü tek kullanımlık belge döngüsünü gösterir. Motor RenderReport’u üretir; kuyruk ise sizin altyapınızdır.

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Observability\RenderReport;
use Psr\Log\LoggerInterface;

/**
 * One batch worker iteration: render, emit, release, measure.
 *
 * The factory and its registries are process-lifetime singletons; the
 * document is disposable. Retained memory must return to baseline between
 * iterations or the worker is leaking.
 *
 * @param iterable<int, callable(\NextPDF\Core\Document): \NextPDF\Core\Document> $jobs
 */
function runBatch(
    DocumentFactoryInterface $factory,
    LoggerInterface $logger,
    iterable $jobs,
): void {
    foreach ($jobs as $jobId => $build) {
        $startedAt = hrtime(true);

        // Fresh, disposable document — shares the warmed registries.
        $doc = $factory->create();
        $doc = $build($doc);
        $bytes = $doc->getPdfData();

        // Hand the bytes off to your sink (object store, response, etc.).
        unset($doc, $bytes); // let the per-render state go

        $elapsedMs = (hrtime(true) - $startedAt) / 1_000_000;

        $logger->info('pdf.render.complete', [
            'job_id'          => $jobId,
            'render_time_ms'  => round($elapsedMs, 2),
            'peak_memory_mb'  => round(memory_get_peak_usage(true) / 1_048_576, 2),
        ]);
    }
}

Buradaki unset() çağrısı görsel bir ayrıntı değildir. İşleme başına durumun her yinelemede serbest bırakılması amaçlanır; böylece tutulan bellek temel değerine geri döner. Temel değeri yinelemeler boyunca yükselen bir çalışan, bu döngünün önlemek üzere tasarlandığı başarısızlık biçimidir.

Yaygın yanlış anlama

En önemli yanlış anlama, “NextPDF saniyede kaç PDF üretebilir?” sorusunun tek bir cevabı varmış gibi düşünmektir. Tek bir cevabı yoktur ve böyle bir rakam vermek, filoların yanlış boyutlandırılmasına yol açar. İşleme maliyetini belge belirler; bu nedenle üzerinde çalışmaya değer tek sayı, motorun kendi işleme başına raporuyla, kendi şablonlarınızda ölçülen sayıdır. Arkasındaki belge, donanım ve yöntem olmadan verilen bir rakam, veri değil süstür.

İkinci yanlış anlama, izlenmesi gereken şeyin tepe bellek olduğudur. Tepe değer geçicidir ve beklenir — geri döner. Bir toplu işi sonlandıran sayı, geri dönmeyen tutulan bellektir. Motorun bu ikisini ayırmasının nedeni tam olarak budur.

Sınırlar ve kapsam

• Evrensel bir veri çıkışı rakamı yoktur ve bu sayfa bilinçli olarak hiçbir rakam belirtmez. İşleme maliyeti belgelerinize bağlıdır; işleme başına raporla ölçün.
• Sınırlı bellek, tek kullanımlık belge modelinin kullanılmasına bağlıdır. Bir belgeyi birçok işleme boyunca tutmak veya değiştirilebilir işleme başına durumu paylaşmak, bu güvenceyi ortadan kaldırır. Çerçeve köprüleri varsayılan olarak güvenli yapıyı kullanır. Elle yapılan kablajın bunu yinelemesi gerekir.
• Görüntü önbelleği sınırsız değil, sınırlıdır. Yoğun benzersiz görüntü iş yükleri altında LRU, öğeleri çıkarır. Bu, bir gerileme değil, tasarımın kendisidir.
• Çalışan havuzu boyutlandırması, kuyruk seçimi ve otomatik ölçekleme, motorun dışında kalan dağıtım kararlarıdır. NextPDF, ölçümleri ve sınırlı ilkel yapıyı sağlar. Kuyruğunuzu çalıştırmaz.
• RenderReport, bir karar değil, veridir. Bir işlemede ne olduğunu söyler. Bunu bir kapasite planına dönüştürmek sizin analizinizdir.
• Bu sayfa, ölçüm yüzeyi için kıyaslama destekli ve bellek modeli için kod desteklidir. Belirli bir orana dair hiçbir iddiada bulunmaz.

Queued high-volume generation primitives — edition availability

Edition	Availability
Core	○ Tek kullanımlık belge modeli, paylaşılan değişmez kayıt defterleri, işleme başına RenderReport ve bellek parçalanması çözümleyicisi Core kapsamındadır. Sade yüksek hacimli PDF oluşturma için ticari bir katmana gerek yoktur.
Pro	○ Aynı ilkel yapılar; ticari özellikler (imzalama, PDF/A) varsaymanız değil, ölçmeniz gereken işleme başına maliyet ekler.
Enterprise	○ Aynı ilkel yapılar; yapılandırılmış fatura ve doğrulama işleri, yük ve kural kümesi boyutuyla ölçeklenen ek işleme başına maliyet ekler.

İlgili belgeler

• Bellek ve akış — motorun büyük belgelerde belleği nasıl sınırlı tuttuğu ve nerede akış kullandığı.
• Dürüst kıyaslama — yöntemi olmayan bir kıyaslama sayısının ne değer taşıdığı ve NextPDF’in performansı nasıl raporladığı.
• Üretimde NextPDF işletme — toplu iş gerçekten çalışmaya başladığında işleme başına raporları sağlık sinyallerine dönüştürme.

Sözlük

• Tek kullanımlık belge — tek bir işleme için oluşturulan ve sonrasında atılan bir belge örneği; böylece hiçbir durum bir sonraki işlemeye sızmaz.
• Paylaşılan kayıt defteri — süreç ömrü boyunca yaşayan, ısınma sonrası değişmez durum (yazı tipleri, görüntü önbelleği); işleme başına maliyet olmadan işlemeler arasında yeniden kullanılır.
• Tepe bellek — işleme sırasındaki geçici en yüksek değer; beklenir ve temel değerine geri döner.
• Tutulan bellek — bir işleme tamamlandıktan sonra hâlâ tutulan bellek; işlemeler boyunca yükselen tutulan temel değeri bir sızıntıdır.
• Çalışan — işleme işlerini bir kuyruktan çeken uzun ömürlü süreç; bir toplu işi atlatabilmek için bellek bakımından sınırlı kalması gerekir.
• RenderReport — motorun, gerçek verilerden kapasite boyutlandırmak için kullanılan değişmez işleme başına ölçüm anlık görüntüsü (süre, tepe bellek, sayfa sayısı, uyarılar).