Technisch artikel

HotPDF: externe pdf-documenten streamen via range coalescing

Een PDF die vanaf een lokale schijf meteen opent, kan enkele seconden doen over het tonen van zijn eerste pagina als dezelfde bytes van een HTTP-server met range requests komen, ook al is het bestand maar een paar megabyte en is de link snel. Bandbreedte is het probleem niet. Het aantal aanvragen is dat wel, en het middel is honderden kleine verspreide reads omzetten in een handjevol gecachte blokken en dan alleen vooruit lezen zolang het toegangspatroon sequentieel blijft

Waarom laadt dezelfde PDF meteen van schijf en kruipert hij over HTTP?

Een PDF-parser leest een bestand niet van voor naar achter. Hij navigeert erin. De structuur in ISO 32000-1 §7.5 zet de ingang achteraan: de parser zoekt naar de laatste kilobyte voor startxref, springt terug naar de kruisverwijzingstabel, lost de trailerdictionary op, volgt een referentie naar de Catalog, dan naar de wortel van de paginaboom, dan naar een paginaknoop, dan naar de resourcedictionary van die pagina. Elke sprong leest tientallen bytes op een andere offset, en een incrementeel bijgewerkt bestand herhaalt de wandeling één keer per revisie via de /Prev-keten

Op een lokaal bestand is dit patroon vrijwel gratis, want het besturingssysteem heeft de omliggende 4 KiB-pagina al in zijn file cache zitten en de tweede read kost een geheugenkopie. Een netwerktransport heeft zulke lokaliteit niet. Elke read wordt een aanvraag met zijn eigen latentie, en de rekenkunde is genadeloos: tegen 40 ms per round trip tellen 300 kleine reads op tot twaalf seconden wachten terwijl de draad vooral lui ligt. Minder lezen is geen optie, want de parser heeft precies de bytes nodig die hij vraagt. Wat kan veranderen is hoeveel elke fysieke aanvraag terugbrengt

Je transport in THPDFCoalescingRandomAccessSource wikkelen

HotPDF laadt documenten uit elke klasse die afstamt van THPDFRandomAccessSource, en THPDFCoalescingRandomAccessSource zit tussen die klasse en de parser in. Elke read wordt afgerond op een uitgelijnd blok en het blok blijft in het geheugen. BlockSize staat standaard op 262.144 bytes en MaxCacheBytes op 2.097.152, dus acht blokken blijven resident en de minst recent gebruikte verdwijnt zodra het budget vol is. De 40-byte-lookup van de parser voor een trailersleutel trekt de 256 KiB eromheen naar binnen, en het volgende dozijn reads in die buurt (kruisverwijzingsentries, de Catalog, paginaboomsleutels) komt uit het geheugen

Je eigen klasse blijft dun. Twee methoden zijn verplicht: GetSize en ReadAt. Override ReadAtCancellable als je HTTP-client een aanvraag die al onderweg is kan afbreken, en override IsRangeAvailable als de bron een download is die nog loopt. De wrapper stelt die vraag vóór elke ophaal: ligt een heel blok er nog niet, dan probeert hij het opnieuw met alleen de gevraagde bytes, en ontbreken die ook, dan komt de read kort terug in plaats van te blokkeren

Diagram van blokcoalescing in HotPDF: verspreide parser-seeks worden opgehoogd naar gecachte blokken van 256 KiB zodat latere reads in dezelfde buurt uit het geheugen komen
reads worden standaard opgehoogd naar gecachte blokken van 256 KiB, dus het gestrooi van de parser kost één netwerkoverdracht per buurt
type
  // TMyHttpClient staat voor je eigen HTTP-clientklasse
  THttpRangeSource = class(THPDFRandomAccessSource)
  private
    FClient: TMyHttpClient;
    FUrl: string;
    FSize: Int64;
  public
    constructor Create(const AUrl: string);
    function GetSize: Int64; override;
    function ReadAt(Offset: Int64; var Buffer; Count: Longint): Longint; override;
    function ReadAtCancellable(Offset: Int64; var Buffer; Count: Longint;
      CancellationToken: THPDFCancellationToken): Longint; override;
  end;

var
  Raw: THttpRangeSource;
  Cached: THPDFCoalescingRandomAccessSource;
  Pdf: THotPDF;
begin
  Raw := THttpRangeSource.Create('https://files.example.com/contract.pdf');
  // OwnsSource=True: de wrapper geeft Raw vrij; blokken van 256 KiB, budget 8 MiB
  Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
  Cached.MaxReadAheadBlocks := 8;   // valid range 1..32
  Pdf := THotPDF.Create(nil);
  try
    // OwnsSource=True opnieuw: Pdf geeft Cached vrij, die Raw vrijgeeft
    if Pdf.LoadFromRandomAccessSource(Cached, True) > 0 then
      RenderFirstPage(Pdf);   // je eigen code
  finally
    Pdf.Free;
  end;
end;

Asynchroon prefetchen en adaptieve read-ahead staan allebei aan zodra de wrapper is gebouwd, dus het voorbeeld raakt alleen het plafon van het venster aan. De constructor valideert zijn argumenten vooraf: BlockSize moet tussen 4.096 en 16.777.216 bytes liggen en MaxCacheBytes moet minstens één blok aankunnen, anders krijg je een ERangeError voordat er ook maar één byte beweegt

De expliciete wrapper is niet streng nodig. Geef LoadFromRandomAccessSource een kale bron en HotPDF wikkelt hem voor je in, met het raw-cachebeleid dat je kunt lezen en veranderen via GetCacheAdmissionPolicy en SetCacheAdmissionPolicy op de laag clkRawCompressed: acht entries, in totaal 2 MiB, 256 KiB per entry. Geef je eigen THPDFCoalescingRandomAccessSource door en hij wordt precies zoals geconfigureerd gebruikt. Voor alles wat een netwerk oversteekt, bouw je de wrapper zelf; dan krijg je de read-aheadknoppen en het volledige statistiekrecord, terwijl de automatische weg alleen hit-, miss-, toelatings- en evictietellingen meldt via GetCacheAdmissionStatistics

Hoe ver vooruit moet er gelezen worden?

Adaptieve read-ahead beslist per document. Met AdaptiveReadAheadEnabled aan wordt elke read die de parser door het geladen document doet, geclassificeerd als sequentieel of willekeurig, en volgt het prefetchvenster een score. Twee opeenvolgende voorwaartse reads openen het venster op twee blokken, vier op vier, zes op acht. Het venster overstijgt nooit MaxReadAheadBlocks, en nooit het aantal blokken dat in MaxCacheBytes past, dus een kleine cache kan niet door zijn eigen prefetch worden ondergelopen

Een read die achteruit springt, of te ver voorbij het einde van de vorige read landt, duwt de score onder nul. Het venster sluit, elke prefetch die ergens anders heen wil wordt geannuleerd, en SuppressedPrefetchCount loopt op. Twee voorwaartse reads later heropent het venster zich op één blok. Die vertraging is het punt: één gelukkige aaneengesloten read middenin een kruisverwijzingsachtervolging herstart geen speculatie

SequentialReadToleranceBytes, standaard 4.096, definieert 'te ver'. Een parser die een content stream afloopt levert niet perfect aaneengesloten offsets; hij slaat hier een length-veld over, daar een inline image-dictionary. Reads die binnen de tolerantie van het vorige einde landen, tellen nog als voorwaarts. Te laag zetten en een gewone voorwaartse scan wordt als willekeurig geklassificeerd, waardoor read-ahead nooit aanspringt. Te hoog zetten en echte willekeurige toegang lijkt sequentieel, en je haalt megabytes binnen die niemand leest. De setter accepteert elke waarde van nul tot BlockSize en reset de score bij een verandering

Groei gaat geleidelijk, instorting onmiddellijk, en die asymmetrie is opzet. Te veel ophalen bij een willekeurige werklast verbrandt echte bandbreedte, en op een gemeterd transport echt geld; te weinig ophalen bij een sequentiële kost een paar extra round trips. Laat AdaptiveReadAheadEnabled aan staan. Uitgeschakeld prefetcht de wrapper na elke read één blok, ongeacht het patroon, wat precies het verkeerde gedrag is terwijl de parser tussen kruisverwijzingssecties springt

Ladderdiagram van adaptieve read-ahead in HotPDF die groeit naar één, twee, vier en acht blokken bij aanhoudende voorwaartse lezingen met een onmiddellijke ineenstorting bij niet-sequentiële toegang
groei beklimt één ladderrung tegelijk terwijl inkrimping onmiddellijk is — de goedkope fout heeft de voorkeur op gemeten verbindingen

De classificatie wordt aangedreven door de stream waar HotPDF tijdens een load uit leest. Trekt je eigen code ook bytes door de wrapper, bijvoorbeeld om een bestand te hashen of een bijlage te extraheren, roep dan na elke read ObserveReadPattern aan met offset en lengte zodat het venster ook op dat verkeer reageert. Weet je al welke bytes de volgende keer nodig zijn, dan start PrefetchRange direct een achtergrond-ophaalactie; IsPrefetchActive meldt of er nog een draait

Hot houden van blokken als de cache vol is

Evictie puur op least-recently-used heeft een bekende zwakte. Eén lange voorwaartse pas, zeg door een grote ingebedde afbeelding, duwt elk blok weg waar de parser steeds terugkomt, inclusief de kruisverwijzings- en Catalog-blokken die hij op de volgende pagina weer nodig heeft. THPDFCoalescingRandomAccessSource telt hoe vaak om elk blok is gevraagd, en zodra het budget vol is, komt een nieuw blok alleen de cache in als het minstens zo vaak is gevraagd als het blok dat hij zou vervangen. Anders gaat de read rechtstreeks naar je bron voor exact de gevraagde bytes, en RejectionCount en FrequencyRejectionCount leggen het vast

Die regel staat standaard aan (het constructorargument AdaptiveAdmission). ConfigureCacheAdmission verandert het bytebudget, het plafon per entry, een optionele entrytelling-grens en de toelatingsregel op een draaiende wrapper; hij annuleert lopende prefetch en snoeit de cache ter plekke terug op de nieuwe grenzen

Annulering die het transport werkelijk stopt

Prefetch draait op één achtergrondthread, en de wrapper annuleert hem zodra het afronden niet meer loont. Een voorgrondread voor bytes buiten het gebied dat wordt geprefetcht annuleert hem, zodat de pagina waar de gebruiker om vroeg nooit achter speculatief verkeer wacht. Een willekeurige read annuleert hem. De wrapper slopen, of CancelPrefetch of ClearCache aanroepen, annuleert hem en wacht tot de thread uitstapt. Elk van deze zet de THPDFCancellationToken die de prefetchthread in je ReadAtCancellable doorgeeft

Of bytes echt stoppen met stromen hangt af van je override. De standaard ReadAtCancellable op THPDFRandomAccessSource controleert het token voor en na een gewone ReadAt, wat voor een file share volstaat maar een half afgeronde HTTP-response van 256 KiB gewoon laat aflopen. Een client die de response-body in brokken leest, kan het token tussen brokken controleren en afbreken:

function THttpRangeSource.ReadAt(Offset: Int64; var Buffer;
  Count: Longint): Longint;
begin
  Result := ReadAtCancellable(Offset, Buffer, Count, nil);
end;

function THttpRangeSource.ReadAtCancellable(Offset: Int64; var Buffer;
  Count: Longint; CancellationToken: THPDFCancellationToken): Longint;
var
  Status: Integer;
begin
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
  // GetRange en zijn callback zijn de API van je client: hij stuurt
  // "Range: bytes=Offset-(Offset+Count-1)" en roept de callback tussen bodybrokken aan
  Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
    function: Boolean
    begin
      Result := (CancellationToken <> nil) and
        CancellationToken.IsCancellationRequested;
    end);
  // 200 in plaats van 206 betekent dat de server Range negeerde en het hele bestand stuurde
  if Status <> 206 then
    raise EStreamError.CreateFmt('Range request not honored (HTTP %d)', [Status]);
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
end;

De statuscontrole dekt de valkuil waar de meeste HTTP-bronnen het eerst tegenaan lopen. RFC 9110 §14 laat een server een Range-header negeren en met 200 de volledige representatie antwoorden, en sommige CDN- en proxyconfiguraties doen dat precies voor bepaalde bestanden. Een bron die de eerste Count bytes van een 200-response kopieert, geeft de parser bytes vanaf offset nul, op welke offset hij ook vroeg. Ook de retourwaarden tellen: de wrapper gooit een EStreamError als ReadAt een negatieve telling of meer bytes dan gevraagd meldt, en hij behandelt nul als einde van de data

Het enige token ongelijk nul dat je bron ontvangt hoort bij de prefetchthread. Parserreads tijdens een load bereiken je ReadAtCancellable met een token van nul, dus de load zelf stoppen is een aparte schakelaar: ken een token toe aan THotPDF.OperationCancellationToken, en het documentladen controleert hem onderweg. Hetzelfde tokenmodel drijft de wachtrij uit achtergrondrenderen met een request queue, zodat een viewer een load, zijn renders en zijn speculatieve netwerkverkeer vanaf één sluit-handler kan annuleren

De bereikcachestatistieken lezen

GetStatistics vult een record THPDFRangeCacheStatistics dat scheidt wat jouw transport deed van wat de cache deed. SourceReadCount en SourceBytesRead zijn fysiek verkeer. CacheHitCount en CacheMissCount zijn logisch verkeer. SequentialReadCount en RandomReadCount laten zien hoe het toegangspatroon werd geklassificeerd, CurrentReadAheadBlocks en PeakReadAheadBlocks hoe ver het venster openging, en de vier prefetchtellers of speculatie iets opleverde. CachedRangeCount, CachedBytes, EvictionCount en RejectionCount beschrijven de cache zelf

var
  S: THPDFRangeCacheStatistics;
begin
  Cached.GetStatistics(S);
  Log(Format('physical %d reads / %d bytes, hits %d, misses %d',
    [S.SourceReadCount, S.SourceBytesRead, S.CacheHitCount, S.CacheMissCount]));
  Log(Format('pattern: %d sequential, %d random, peak window %d blocks',
    [S.SequentialReadCount, S.RandomReadCount, S.PeakReadAheadBlocks]));
  Log(Format('prefetch: %d issued, %d completed, %d canceled, %d suppressed',
    [S.PrefetchRequestCount, S.PrefetchCompletedCount,
     S.PrefetchCancelledCount, S.SuppressedPrefetchCount]));
  Log(Format('cache: %d blocks / %d bytes, %d evicted, %d rejected',
    [S.CachedRangeCount, S.CachedBytes, S.EvictionCount, S.RejectionCount]));

  // Afwijzingen die stapelen op een vooral sequentieel document: geef meer ruimte
  if S.RejectionCount > S.CacheHitCount then
    Cached.ConfigureCacheAdmission(16 * 1024 * 1024, Cached.BlockSize, 0);
end;

Drie lezingen vertellen je wat te veranderen. Veel geannuleerde prefetches naast een hoog aantal willekeurige reads betekent dat het document uit de volgorde wordt doorlopen, dus verlaag MaxReadAheadBlocks en stop met betalen voor bandbreedte die je weggooit. Veel misses met het piekvenster vast op 1 betekent dat de tolerantie een patroon weigert dat in feite sequentieel is, dus verhoog SequentialReadToleranceBytes. SourceBytesRead ver boven de bestandsgrootte betekent dat blokken worden ge-evict voordat ze weer worden gebruikt; verhoog MaxCacheBytes voordat je iets anders aanraakt. De afwijzingsdrempel in het voorbeeld is onze eigen startheuristiek, dus stem hem af op jouw verkeer

HotPDF-paneel dat de drie THPDFRangeCacheStatistics-aflezingen in kaart brengt aan de MaxReadAheadBlocks-, SequentialReadToleranceBytes- en MaxCacheBytes-aanpassingen
elke symptoomlezing benoemt zijn oplossing, van het verlagen van het venster bij random loops tot het verbreden van de cache wanneer blokken continu worden ververst

Gelineariseerde bestanden veranderen de rekensom

Beheers je de producent, dan verandert het lineariseren van het document het probleem in plaats van het af te stemmen. ISO 32000-1 Bijlage F plaatst de objecten van de eerste pagina en een hinttabel vooraan in het bestand, zodat een viewer pagina een kan renderen uit de openingsbytes zonder de rest aan te raken. HotPDF legt die weg bloot via GetProgressiveLinearizedLoadInfo en ReadProgressiveLinearizedFirstPageSection, die allebei dezelfde THPDFRandomAccessSource nemen die je voor coalescing zou omwikkelen; de schrijfkant staat beschreven in gelinieariseerde PDF's met hinttabellen genereren

De twee technieken stapelen. Coalescing maakt elk document draaglijk over een trage link, inclusief bestanden van derden die je niet opnieuw kunt opslaan; linearisatie laat de eerste pagina snel aankomen op documenten die je zelf produceert. Bestanden op een lokale schijf die te groot zijn voor het geheugen zijn een ander probleem zonder round-trip-latentie om terug te verdienen, en de mapped-file- en lazy-stream-wegen in de direct file API-workflow passen daar beter bij

De klassen voor random-access-bronnen, de coalescing-wrapper, de cache-toelatingsbeleiden en de progressieve gelinieariseerde laadaanroepen worden allemaal geleverd met HotPDF, een native Delphi- en C++Builder-PDF-component met volledige broncode. Licenties en de complete API-referentie staan op de HotPDF Delphi PDF-componentpagina