Artículo técnico

Transmita PDF remotos en Delphi: fusión de rangos HotPDF

Un PDF que abre al instante desde un disco local puede tardar varios segundos en mostrar su primera página cuando los mismos bytes vienen de un servidor HTTP que responde range requests, aunque el archivo sea de apenas unos megabytes y el enlace sea rápido. El ancho de banda no es el problema. El conteo de requests lo es, y la cura es convertir cientos de lecturas diminutas dispersas en unas pocas docenas de bloques cacheados, y luego leer adelante solo mientras el patrón de acceso sigue secuencial

¿Por qué el mismo PDF carga al instante en local y se arrastra por la red?

Un parser de PDF no lee un archivo de frente a atrás. Lo navega. La estructura en ISO 32000-1 §7.5 pone el punto de entrada al final: el parser busca el último kilobyte por startxref, salta de vuelta a la tabla de referencias cruzadas, resuelve el diccionario trailer, sigue una referencia al Catalog, luego a la raíz del árbol de páginas, luego a un nodo de página, luego al diccionario de recursos de esa página. Cada salto lee decenas de bytes de un offset distinto, y un archivo con actualizaciones incrementales repite el recorrido una vez por revisión a través de la cadena /Prev

Sobre un archivo local este patrón es casi gratis, porque el sistema operativo ya sostiene la página de 4 KiB circundante en su caché de archivos y la segunda lectura cuesta una copia de memoria. Un transporte de red no tiene esa localidad. Cada lectura se vuelve un request con su propia latencia, y la aritmética es brutal: a 40 ms por viaje de ida y vuelta, 300 lecturas pequeñas suman doce segundos de espera mientras el cable está mayormente ocioso. Leer menos no es opción, porque el parser necesita exactamente los bytes que pide. Lo que puede cambiar es cuánto trae de vuelta cada request físico

Envolver su transporte en THPDFCoalescingRandomAccessSource

HotPDF carga documentos desde cualquier clase que descienda de THPDFRandomAccessSource, y THPDFCoalescingRandomAccessSource se sienta entre esa clase y el parser. Cada lectura se redondea hacia arriba a un bloque alineado y el bloque se queda en memoria. BlockSize viene en 262,144 bytes y MaxCacheBytes en 2,097,152, así que ocho bloques se mantienen residentes y el usado menos recientemente se va cuando el presupuesto se llena. El lookup de 40 bytes del parser de una clave del trailer trae los 256 KiB de alrededor, y la próxima docena de lecturas en ese vecindario (entradas de referencias cruzadas, el Catalog, claves del árbol de páginas) salen de memoria

Su propia clase se mantiene delgada. Dos métodos son obligatorios: GetSize y ReadAt. Sobrescriba ReadAtCancellable cuando su cliente HTTP pueda abortar un request en vuelo, y sobrescriba IsRangeAvailable cuando la fuente sea una descarga todavía en curso. El wrapper hace esa pregunta antes de cada fetch: si un bloque entero todavía no está ahí reintenta con solo los bytes pedidos, y si esos también faltan la lectura vuelve corta en lugar de bloquearse

Diagrama de la coalescencia de bloques de HotPDF: las búsquedas dispersas del parser se redondean hacia arriba a bloques en caché de 256 KiB, de modo que las lecturas posteriores en la misma vecindad nunca toquen la red
cada lectura se atiende desde un bloque de 256 KiB en caché, de modo que la dispersión del parser sigue costando una transferencia de red por vecindad
type
  // TMyHttpClient representa su propia clase de cliente HTTP
  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: el wrapper libera Raw; bloques de 256 KiB, presupuesto de 8 MiB
  Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
  Cached.MaxReadAheadBlocks := 8;   // rango válido 1..32
  Pdf := THotPDF.Create(nil);
  try
    // OwnsSource=True otra vez: Pdf libera Cached, que libera Raw
    if Pdf.LoadFromRandomAccessSource(Cached, True) > 0 then
      RenderFirstPage(Pdf);   // código suyo
  finally
    Pdf.Free;
  end;
end;

El prefetch asíncrono y la lectura anticipada adaptativa vienen ambos activados tan pronto se construye el wrapper, así que el sample solo toca el techo de la ventana. El constructor valida sus argumentos por adelantado: BlockSize debe estar entre 4,096 y 16,777,216 bytes y MaxCacheBytes debe caber al menos un bloque, de lo contrario recibe un ERangeError antes de que se mueva un solo byte

No necesita estrictamente el wrapper explícito. Entréguele a LoadFromRandomAccessSource una fuente corriente y HotPDF la envuelve por usted, usando la política de caché cruda que puede leer y cambiar a través de GetCacheAdmissionPolicy y SetCacheAdmissionPolicy con la capa clkRawCompressed: ocho entradas, 2 MiB en total, 256 KiB por entrada. Pase su propio THPDFCoalescingRandomAccessSource y se usa exactamente como está configurado. Para cualquier cosa que cruce una red, construya el wrapper usted mismo; obtiene las perillas de read-ahead y el record de estadísticas completo, mientras que el camino automático solo reporta conteos de hit, miss, admisión y expulsión a través de GetCacheAdmissionStatistics

¿Qué tan adelante debería leer?

La lectura anticipada adaptativa decide por documento. Con AdaptiveReadAheadEnabled activado, cada lectura que el parser hace a través del documento cargado se clasifica como secuencial o aleatoria, y la ventana de prefetch sigue un puntaje. Dos lecturas hacia adelante consecutivas abren la ventana a dos bloques, cuatro la abren a cuatro, seis la abren a ocho. La ventana nunca excede MaxReadAheadBlocks, y nunca excede la cantidad de bloques que caben en MaxCacheBytes, así que una caché pequeña no puede ser inundada por su propio prefetch

Una lectura que salta hacia atrás, o que aterriza demasiado lejos del final de la lectura anterior, baja el puntaje por debajo de cero. La ventana se cierra, cualquier prefetch que iba hacia otro lado se cancela, y SuppressedPrefetchCount sube. Dos lecturas hacia adelante después la ventana reabre en un solo bloque. Ese rezago es la idea: una lectura contigua afortunada en el medio de una persecución de referencias cruzadas no reinicia la especulación

SequentialReadToleranceBytes, 4,096 por defecto, define «demasiado lejos». Un parser recorriendo un content stream no produce offsets perfectamente contiguos; se salta un campo de largo aquí, un diccionario de imagen en línea allá. Las lecturas que aterrizan dentro de la tolerancia del final anterior todavía cuentan como hacia adelante. Póngalo muy bajo y un escaneo normal hacia adelante se clasifica como aleatorio, así que el read-ahead nunca se activa. Póngalo muy alto y el acceso aleatorio genuino parece secuencial, y usted trae megabytes que nadie lee. El setter acepta cualquier valor desde cero hasta BlockSize y resetea el puntaje cuando cambia

El crecimiento es gradual, el colapso es inmediato, y esa asimetría es deliberada. Sobre-traer en una carga de trabajo aleatoria quema ancho de banda real, y en un transporte medido dinero real; sub-traer en una secuencial cuesta unos viajes de ida y vuelta extra. Deje AdaptiveReadAheadEnabled encendido. Apagado, el wrapper hace prefetch de un bloque después de cada lectura sin importar el patrón, que es exactamente el comportamiento equivocado mientras el parser salta entre secciones de referencias cruzadas

Diagrama de escalera de la lectura anticipada adaptativa de HotPDF que crece a uno, dos, cuatro y ocho bloques en lecturas hacia adelante sostenidas, con un colapso inmediato ante accesos fuera de orden
el crecimiento sube un peldaño a la vez, mientras que el colapso es inmediato — el error barato se prefiere en transportes medidos

La clasificación la maneja el stream desde el que HotPDF lee durante una carga. Si su propio código también jala bytes a través del wrapper, por ejemplo para hashear un archivo o extraer un adjunto, llame a ObserveReadPattern con el offset y el largo después de cada lectura para que la ventana reaccione también a ese tráfico. Cuando ya sabe qué bytes se van a querer después, PrefetchRange arranca un fetch de fondo directo; IsPrefetchActive reporta si uno sigue corriendo

Conservar los bloques calientes cuando la caché se llena

La expulsión por usado menos recientemente a secas tiene una debilidad conocida. Una pasada larga hacia adelante, digamos a través de una imagen embebida grande, bota cada bloque al que el parser sigue volviendo, incluidos los bloques de referencias cruzadas y Catalog que va a necesitar otra vez en la próxima página. THPDFCoalescingRandomAccessSource cuenta cuántas veces se ha pedido cada bloque, y una vez que el presupuesto se llena un bloque nuevo solo entra a la caché si fue pedido al menos tantas veces como el bloque que reemplazaría. Si no, la lectura va directo a su fuente por exactamente los bytes pedidos, y RejectionCount y FrequencyRejectionCount lo registran

Esa regla viene encendida por defecto (el argumento de constructor AdaptiveAdmission). ConfigureCacheAdmission cambia el presupuesto de bytes, el techo por entrada, un límite opcional de conteo de entradas y la regla de admisión sobre un wrapper vivo; cancela cualquier prefetch corriendo y recorta la caché a los nuevos límites en el momento

Cancelación que realmente detiene la transferencia

El prefetch corre en un solo hilo de fondo, y el wrapper lo cancela tan pronto deja de valer la pena terminarlo. Una lectura en primer plano por bytes fuera del rango en prefetch lo cancela, así que la página que el usuario pidió nunca espera detrás de tráfico especulativo. Una lectura aleatoria lo cancela. Destruir el wrapper, o llamar a CancelPrefetch o ClearCache, lo cancela y espera a que el hilo salga. Cada una de estas cosas activa el THPDFCancellationToken que el hilo de prefetch pasa a su ReadAtCancellable

Que los bytes realmente dejen de fluir depende de su sobrescritura. El ReadAtCancellable por defecto en THPDFRandomAccessSource chequea el token antes y después de un ReadAt corriente, lo que basta para un file share pero deja que una respuesta HTTP de 256 KiB a medio terminar corra hasta el final. Un cliente que lee el body de la respuesta en chunks puede chequear el token entre chunks y abortar:

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 y su callback son la API de su cliente: envía
  // "Range: bytes=Offset-(Offset+Count-1)" y llama al callback entre chunks del body
  Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
    function: Boolean
    begin
      Result := (CancellationToken <> nil) and
        CancellationToken.IsCancellationRequested;
    end);
  // 200 en lugar de 206 significa que el servidor ignoró Range y mandó el archivo completo
  if Status <> 206 then
    raise EStreamError.CreateFmt('Range request not honored (HTTP %d)', [Status]);
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
end;

El chequeo de estado cubre la trampa en la que la mayoría de las fuentes HTTP tropiezan primero. RFC 9110 §14 deja que un servidor ignore un header Range y responda 200 con la representación completa, y algunas configuraciones de CDN y proxy hacen exactamente eso con ciertos archivos. Una fuente que copia los primeros Count bytes de una respuesta 200 le entrega al parser bytes desde el offset cero sin importar qué offset pidió. Los valores de retorno importan también: el wrapper lanza un EStreamError si ReadAt reporta un conteo negativo o más bytes de los pedidos, y trata el cero como fin de data

El único token no nulo que su fuente recibe pertenece al hilo de prefetch. Las lecturas del parser durante una carga llegan a su ReadAtCancellable con un token nil, así que detener la carga misma es un interruptor separado: asigne un token a THotPDF.OperationCancellationToken, y la carga del documento lo chequea sobre la marcha. El mismo modelo de tokens maneja la cola descrita en renderizado en segundo plano con una cola de solicitudes, así que un visor puede cancelar una carga, sus renders y su tráfico de red especulativo desde un solo handler de cierre

Cómo leer las estadísticas de la caché de rangos

GetStatistics llena un record THPDFRangeCacheStatistics que separa lo que hizo su transporte de lo que hizo la caché. SourceReadCount y SourceBytesRead son tráfico físico. CacheHitCount y CacheMissCount son tráfico lógico. SequentialReadCount y RandomReadCount muestran cómo se clasificó el patrón de acceso, CurrentReadAheadBlocks y PeakReadAheadBlocks muestran qué tan lejos se abrió la ventana, y los cuatro contadores de prefetch muestran si la especulación valió la pena. CachedRangeCount, CachedBytes, EvictionCount y RejectionCount describen a la caché misma

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]));

  // Rechazos acumulándose en un documento mayormente secuencial: dele más espacio
  if S.RejectionCount > S.CacheHitCount then
    Cached.ConfigureCacheAdmission(16 * 1024 * 1024, Cached.BlockSize, 0);
end;

Tres lecturas le dicen qué cambiar. Muchos prefetch cancelados junto a un conteo alto de lecturas aleatorias significan que el documento se está recorriendo fuera de orden, así que baje MaxReadAheadBlocks y deje de pagar por ancho de banda que bota. Muchos miss con la ventana pico trabada en 1 significan que la tolerancia está rechazando un patrón que en la práctica es secuencial, así que suba SequentialReadToleranceBytes. Un SourceBytesRead muy por encima del tamaño del archivo significa que los bloques se expulsan antes de volverse a usar; suba MaxCacheBytes antes de tocar cualquier otra cosa. El umbral de rechazo del sample es nuestra heurística de arranque propia, así que afínela contra su tráfico

Panel de HotPDF que mapea las tres lecturas de THPDFRangeCacheStatistics a los ajustes MaxReadAheadBlocks, SequentialReadToleranceBytes y MaxCacheBytes
cada lectura de síntoma nombra su solución, desde bajar la ventana en recorridos aleatorios hasta ensanchar la caché cuando los bloques sufren thrashing

Los archivos linearizados cambian la aritmética

Si usted controla al productor, linearizar el documento cambia el problema en lugar de afinarlo. El Anexo F de ISO 32000-1 coloca los objetos de la primera página y una tabla de hints al frente del archivo, así que un visor puede renderizar la página uno desde los bytes iniciales sin tocar el resto. HotPDF expone ese camino a través de GetProgressiveLinearizedLoadInfo y ReadProgressiveLinearizedFirstPageSection, ambos de los cuales toman el mismo THPDFRandomAccessSource que usted envolvería para coalescencia; el lado de escritura está cubierto en generar PDFs linearizados con tablas de hints

Las dos técnicas se componen. La coalescencia hace tolerable cualquier documento sobre un enlace lento, incluidos archivos de terceros que usted no puede volver a guardar; la linealización hace que la primera página llegue rápido en los documentos que usted produce. Los archivos en disco local demasiado grandes para sostenerlos en memoria son un problema distinto sin latencia de ida y vuelta que amortizar, y los caminos de archivo mapeado y stream perezoso en el flujo de trabajo de la API de archivo directo les quedan mejor

Las clases de fuente de acceso aleatorio, el wrapper de coalescencia, las políticas de admisión de caché y las llamadas de carga linearizada progresiva vienen todas con HotPDF, un componente PDF nativo para Delphi y C++Builder con código fuente completo. Las licencias y la referencia completa de la API están en la página del componente PDF de HotPDF para Delphi