Artykuł techniczny

Progressive download i cancel w PDFium w Delphi (FPDFAvail)

Niepusty uchwyt dokumentu z liczbą stron równą zero to to, co FPDFAvail_GetDocument może oddać, gdy zawołano go na PDF-ie, który nigdy nie był zlinearyzowany — nawet po tym, jak FPDFAvail_IsDocAvail raportował PDF_DATA_AVAIL. Uchwyt wygląda na otwarty, nic nie narzeka, a przeglądarka pokazuje pusty dokument. API dostępności PDFium czyta zlinearyzowany układ Aneksu F ISO 32000-1; każdy inny plik musi być kompletny i otwierany zwykłą ścieżką własnego dokumentu. Ta decyzja o rozdzielaniu ruchu to połowa tego, w co wpisuje się otwieranie PDF-a w trakcie pobierania. Druga połowa to użytkownik, który zamyka kartę na ćwiartce pliku i chwilę później otwiera ten sam link ponownie

Pętla dostępności stojąca za TPdfProgressiveDocument

W PDFium Component cała sesja mieszka w TPdfProgressiveDocument, podklasie TPdf, która trzyma dostawcę dostępności PDFium przy życiu, dopóki strumień o dostępie swobodnym się zapełnia. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) bierze strumień nośny i logiczny rozmiar zdalnego pliku (Content-Length, nie bieżącą długość twojego lokalnego magazynu), wpina callback IsDataAvail i callback AddSegment, i woła FPDFAvail_Create. Gdy OpenProgressiveDocument się uda, obiekt zachowuje się jak każdy inny aktywny TPdf: strony, tekst, renderowanie i zapis działają przez zwykłe człony

Każdy krok parsowania to pytanie do twojego kodu. Gdy PDFium chce zakresu, komponent odpowiada tak, jeśli zakres leży w ciągłym prefiksie opisanym przez AvailableByteCount albo w zakresie już dokończonym przez scheduler RangeRequests. Handler OnDataAvailable dostaje potem ostatnie słowo — tak odpowiada rozproszony cache za zakresy, których żadno z tamtych nie opisze. CheckDocumentAvailability zwraca jedną z trzech wartości TPdfDataAvailability (pdaAvailable, pdaNotAvailable, pdaError) i oddaje zakresy bajtów, o które pytał PDFium, jako posortowaną, scaloną tablicę TPdfDownloadRanges. Te zakresy są już wkolejkowane na schedulerze z priorytetem rrpImmediate, zanim je zobaczysz, więc tablica podpowiedzi służy do logowania i wyświetlania postępu; kolejka robocza to RangeRequests

// FetchRange to twój transport (HTTP Range GET, gniazdo, czytnik blobów):
// zapisuje Size bajtów w Offset do Store i zwraca, ile dotarło
function FetchRange(Store: TStream; Offset, Size: UInt64): UInt64; forward;

procedure OpenWhileDownloading(Pdf: TPdfProgressiveDocument; Store: TStream;
  RemoteSize: UInt64);
const
  MaxRounds = 64;
var
  Hints: TPdfDownloadRanges;
  State: TPdfDataAvailability;
  Request: TPdfRangeRequest;
  Round: Integer;
begin
  Pdf.BeginProgressiveLoad(Store, RemoteSize, False);
  State := pdaNotAvailable;
  for Round := 1 to MaxRounds do
  begin
    State := Pdf.CheckDocumentAvailability(Hints);
    if State <> pdaNotAvailable then
      Break;
    // Podpowiedzi są już wkolejkowane; najpierw zapisz bajty, potem dokończ
    while Pdf.RangeRequests.TryDequeue(Request) do
      Pdf.RangeRequests.CompleteRequest(Request,
        FetchRange(Store, Request.Offset, Request.Size));
  end;
  if State <> pdaAvailable then
    raise EPdfError.Create('The document could not be discovered');
  Pdf.OpenProgressiveDocument;
end;

Dwa detale w tej pętli dźwigają całość. Limit rund ma znaczenie, bo martwy link każe CheckDocumentAvailability pytać o te same zakresy w nieskończoność, a nieograniczona pętla zamienia awarię sieci w zawieszony UI. Kolejność ma znaczenie, bo scheduler serializuje swój stan sekcją krytyczną, ale nic nie robi dla TStream.Position na magazynie nośnym: wątek transportowy musi zapisać bajty odpowiedzi do strumienia przed wołaniem CompleteRequest, bo w chwili opublikowania dokończenia PDFium może ten zakres przeczytać, a współbieżni pisarze potrzebują I/O pozycjonowanego albo własnej blokady

Pętla dostępności TPdfProgressiveDocument w PDFium Component: BeginProgressiveLoad tworzy dostawcę FPDFAvail, CheckDocumentAvailability oddaje posortowane, scalone podpowiedzi pobierania wkolejkowane z priorytetem rrpImmediate, transport zapisuje bajty do magazynu, zanim CompleteRequest opublikuje każdy zakres do PDFium, a pętla ma limit 64 rund, bo martwy link pyta o te same zakresy w kółko
Zapisz bajty, potem dokończ żądanie: w chwili opublikowania dokończenia PDFium może ten zakres przeczytać, a nic nie chroni za ciebie pozycji strumienia

Dlaczego AvailableByteCount odmawia ruchu do tyłu?

AvailableByteCount tylko rośnie. Przypisanie mniejszej wartości podnosi EPdfError z komunikatem „Available byte count cannot move backwards", bo skoro callback dostępności powiedział już PDFium, że zakres istnieje, parser mógł już z niego przeczytać i zcache'ować obiekty. Zabranie tych bajtów później zostawiłoby PDFium z obiektami, których źródła odpowiedzi dostępności teraz zaprzeczają. Ten sam setter odrzuca wartości większe niż LogicalFileSize i podnosi „No progressive load is active" poza sesją

Ten ostatni sprawdzian rozstrzyga, gdzie należą bajty, które już masz. Jeśli poprzednia wizyta zostawiła pierwsze 300 KB pliku w cache, podaj tę liczbę jako AInitialAvailableByteCount; komponent odnotowuje ją, zanim ruszy FPDFAvail_Create, więc pierwszy rzut oka PDFium na nagłówek już ją widzi. Przy początkowej liczbie zero Linearization czyta plnUnknown, aż PDFium zobaczy nagłówek; to normalny stan startowy

Podniesienie prefiksu anuluje też pracę. Każde lecące żądanie nachodzące na świeżo ogłoszone bajty jest teraz redundantne, więc scheduler je zrzuca i odpala dla niego OnCancelRequest; spóźnione CompleteRequest dla tego żądania zwraca False. Magazyn zapełniający się nie po kolei nie powinien w ogóle próbować wyrażać się przez prefiks. Dokańczaj zakresy przez scheduler albo odpowiadaj per zakres w OnDataAvailable. Wyjątek podniesiony wewnątrz tego handlera nie przetnie granicy callbacka C, więc komponent go łapie i raportuje zakres jako brakujący, a PDFium po prostu pyta ponownie przy następnym sprawdzianie

Kiedy częściowo pobrany PDF faktycznie się otworzy?

Tylko zlinearyzowany PDF otwiera się, zanim przybędzie cały plik. OpenProgressiveDocument sprawdza właściwość Linearization (plnUnknown, plnNotLinearized, plnLinearized) i wybiera loadera. Zlinearyzowany plik otwiera przez FPDFAvail_GetDocument, jak tylko sekcja pierwszej strony i tabele podpowiedzi są obecne. Niezlinearyzowany plik idzie przez FPDF_LoadCustomDocument na tym samym rekordzie dostępu do pliku, i dla takiego pliku PDFium raportuje dokument jako dostępny dopiero, gdy jest tam każdy bajt. To rozdzielanie ruchu trzyma niepusty uchwyt z zerem stron z akapitu otwierającego z dala od twojej przeglądarki

Jak OpenProgressiveDocument rozdziela ruch częściowego pobrania w PDFium Component: zlinearyzowany plik otwiera się przez FPDFAvail_GetDocument, gdy tylko przybędą sekcja pierwszej strony i tabele podpowiedzi, niezlinearyzowany potrzebuje FPDF_LoadCustomDocument i każdego bajtu, a LoadAvailablePage sprawdza dostępność formularza przez FPDFAvail_IsFormAvail przed kontrolą strony, omijając pułapkę niepustego uchwytu z zerem stron
Przewagę zyskują tylko pliki zlinearyzowane; na czymkolwiek innym FPDFAvail_GetDocument może zwrócić wyglądający na otwarty dokument z zerem stron — dokładnie temu strzeże ten rozdział ruchu

Plik na serwerze rozstrzyga więc, jak szybko pojawi się pierwsza strona. Jeśli czas do pierwszego kadru się liczy, a kontrolujesz stronę publikującą, linearyzuj pliki tam. TPdf.SaveAsLinearized zapisuje układ Aneksu F prosto z komponentu, a przewodnik po Fast Web View i tabelach podpowiedzi omawia, co ten układ zawiera. Dla plików, których nie kontrolujesz, niezlinearyzowany PDF nadal ładuje się przez tę samą pętlę; dochodzi po prostu do pdaAvailable przy 100 procentach zamiast wcześnie

LoadAvailablePage bierze numer strony liczony od 1 i trzyma kolejność, jakiej oczekuje PDFium. Przed pierwszą kontrolą strony biegnie CheckFormAvailability, które owija FPDFAvail_IsFormAvail, i dopiero potem woła FPDFAvail_IsPageAvail. Wynik pfaNotPresent to normalna odpowiedź dla dokumentu bez AcroForm i niczego nie blokuje. Gdy strona jest gotowa, LoadAvailablePage czyni ją aktywną stroną, więc przeglądarka może renderować stronę 1 zlinearyzowanej broszury, podczas gdy późniejsze strony są jeszcze w drodze. Czekanie na stronę ma ten sam kształt co pierwszy listing: wołaj LoadAvailablePage, opróżniaj RangeRequests przy pdaNotAvailable, zatrzymuj się na pdaAvailable albo pdaError i trzymaj limit rund. FirstAvailablePageNumber raportuje stronę, którą słownik linearyzacji desygnuje jako pierwszą, już przeliczone z indeksu PDFium liczonego od zera. Dla niezlinearyzowanego pliku każda strona raportuje od razu pdaAvailable, bo dokument mógł się otworzyć tylko, gdy plik był kompletny

Ponowienia, krótkie odczyty i priorytety w schedulerze zakresów

API FPDFAvail_* samo nie wie nic o sieciach. Mówi, jakich bajtów parser potrzebuje akurat, i pyta ponownie później; nie ma pojęcia żądania, ponowienia ani cancelu. TPdfRangeRequestScheduler dostarcza tych pojęć, a cztery z jego reguł kształtują to, jak piszesz transport

  • Krótka odpowiedź jest traktowana jako postęp. CompleteRequest(Request, BytesReceived) z mniejszą liczbą bajtów niż żądano publikuje prefiks i kolejkuje resztę. Krótka odpowiedź liczy się też jako nieudana próba, więc reszta jest nadal związana MaxRetryCount i zostaje porzucona, gdy ten się wyczerpie; zero bajtów to zwykła nieudana próba
  • MaxRetryCount domyślnie wynosi 2, więc jeden zakres dostaje trzy próby łącznie. FailRequest zwraca True, gdy wkolejkuje zakres ponownie, i False, gdy zakres został porzucony; Statistics.AbandonedRequestCount śledzi, ile ich się poddało
  • MaxRequestSize rozdziela duże zakresy na kawałki w czasie zdejmowania z kolejki, a MergeGap pozwala dwom oczekującym zakresom scalić się przez małą nieznaną lukę, ale nigdy przez bajty już dokończone albo lecące
  • Podpowiedzi z CheckDocumentAvailability i LoadAvailablePage przychodzą z rrpImmediate. Podpowiedzi formularza z bezpośredniego wywołania CheckFormAvailability przychodzą z rrpNormal; gdy LoadAvailablePage robi ten sprawdzian sama, a dane formularza są nieobecne, podpowiedzi są kolejkowane z rrpImmediate. TryDequeue obsługuje zawsze najpierw najwyższy priorytet i najniższy offset w obrębie priorytetu

Reguła priorytetów opłaca się przy prefetchu. Kolejkuj cały plik z rrpBackground tuż po otwarciu dokumentu, a scheduler odejmie wszystko już dokończone albo lecące, więc na łącze idą tylko brakujące bajty. Gdy użytkownik skoczy potem na stronę 40, a podpowiedź tej strony nachodzi na lecący już backgroundowy kawałek, scheduler wyciąga żądanie backgroundowe, odpala dla niego OnCancelRequest, niezachodzące ogony wrzuca z powrotem z priorytetem backgroundowym bez liczenia im ponowienia, a pokrycie kolejkuje jako świeżą pracę immediate. Skok wygrywa połączenie. Bez tego żądanie strony czekałoby za kawałkiem 256 KB, którego nie obchodzi

procedure TDownloadForm.QueueRestOfFile;
var
  Whole: TPdfDownloadRanges;
begin
  FPdf.RangeRequests.MaxRequestSize := 256 * 1024;  // rozmiar kawałka to twoja decyzja
  SetLength(Whole, 1);
  Whole[0].Offset := 0;
  Whole[0].Size := FPdf.LogicalFileSize;
  FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;

// Wołane na wątku roboczym, gdy kończy się jedna odpowiedź HTTP Range.
// WriteAt to twój własny pozycjonowany zapis do magazynu nośnego
procedure TDownloadForm.RangeFinished(const Request: TPdfRangeRequest;
  const Body: TBytes; Succeeded: Boolean);
begin
  if Succeeded and (Length(Body) > 0) then
  begin
    WriteAt(FStore, Request.Offset, Body);              // najpierw bajty
    FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
  end
  else if not FPdf.RangeRequests.FailRequest(Request) then
    TThread.Queue(nil, ShowRangeGaveUp);  // porzucone, albo z anulowanej sesji
end;

Zarówno CompleteRequest, jak i FailRequest wolno wołać z wątku roboczego; scheduler bierze własną blokadę. Żądanie zastąpione albo należące do anulowanej sesji wraca jako False bez dotykania czegokolwiek, więc worker nie musi wiedzieć, dlaczego jego zakres stał się nieaktualny

Co zwalnia CancelProgressiveLoad i w jakiej kolejności?

CancelProgressiveLoad rozbiera sesję w czterech krokach, zawsze w tej samej kolejności: anuluj scheduler zakresów, zamknij dokument, zniszcz uchwyt dostępności przez FPDFAvail_Destroy, potem zwolnij rekordy callbacków i adapter strumienia. Anulowanie schedulera najpierw podbija jego licznik generacji, zrzuca każde oczekujące i lecące żądanie i odpala OnCancelRequest dla każdego lecącego. Dokończenie transportowe, które wyląduje potem, niesie starą generację, a CompleteRequest zwraca False. Dokument zamyka się, zanim odejdą uchwyt dostępności i adapter strumienia, bo PDFium może w trakcie zamykania dokumentu wciąż czytać przez dostawcę dostępu do pliku

Stała kolejność rozbierania w CancelProgressiveLoad w PDFium Component: najpierw anuluj scheduler zakresów, żeby spóźnione dokończenia trafiły w podbity licznik generacji i zwróciły False, zamknij dokument, zanim zniknie adapter dostępu do pliku, zniszcz uchwyt dostępności przez FPDFAvail_Destroy, a dopiero potem zutylizuj rekordy callbacków i zwolnij adapter strumienia
Jedna idempotentna metoda sprząta po nieudanym starcie, anulowaniu przez użytkownika i destruktorze tak samo; przy wątku roboczym piszącym do magazynu własność strumienia zostaje przy tobie
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
  FPdf := TPdfProgressiveDocument.Create(nil);
  // Scheduler żyje tak długo jak FPdf, więc wpnij go raz
  FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;

procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
  Attempt: Cardinal);
begin
  FTransport.Abort(RequestId);   // twój kod: zamknij to gniazdo albo żądanie
end;

procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
  FPdf.CancelProgressiveLoad;
  // ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;

Metoda jest idempotentna i służy jako jedyna ścieżka sprzątania dla trzech sytuacji: BeginProgressiveLoad, które pada w połowie konstrukcji, jawnego cancelu użytkownika i destruktora. BeginProgressiveLoad woła ją też, więc ponowny start tego samego obiektu na nowym URL-u jest w porządku, póki wcześniejsza sesja nie doszła do otwarcia. Gdy OpenProgressiveDocument już się udało, obiekt jest aktywny, a BeginProgressiveLoad podnosi zwykły błąd „Cannot perform this operation on an active"; zawołaj najpierw CancelProgressiveLoad. OnCancelRequest to też jedyne miejsce, gdzie twoje gniazda się zamykają, skoro scheduler nie ma pojęcia, czym jest gniazdo. Wyjątki podniesione wewnątrz niego są połykane per żądanie, więc jedno padające przerwanie nie może zablokować reszty

Kto pisze do magazynu, rozstrzyga, kto go posiada. Przy wątku roboczym piszącym do strumienia nośnego podaj AOwnsStream = False i zwolnij strumień sam, po zatrzymaniu workera. Przekazanie własności znaczy, że cancel zwalnia strumień, podczas gdy zapis już w toku może wciąż być w drodze. Trzymaj własność zawsze, gdy magazyn dotyka wątek inny niż wołający; AOwnsStream = True pasuje tylko do w pełni synchronicznego transportu jak w pierwszym listingu

Funkcje, które czekają na cały plik

Niektóre funkcje potrzebują oryginalnych bajtów pliku, nie sparsowanego dokumentu, i odmawiają niekompletnego źródła przyrostowego z marszu. ReadXmpPacket podnosi „PDF/A metadata is unavailable until progressive loading completes". ValidatePades zwraca wynik, którego SourceStatus to pvssIncomplete, a ValidatePdfMac raportuje niewspierane z komunikatem proszącym o kompletny plik źródłowy. BeginIncrementalSave też zawodzi, bo aktualizacja przyrostowa musi dokleić się do dokładnych bajtów, które zostały wczytane

Sprawdzianem kompletności za nimi wszystkimi jest AvailableByteCount dochodzące do LogicalFileSize. Transport dostarczający wszystko przez scheduler może więc trzymać każdy bajt i nadal zostać poinformowany, że źródło jest niekompletne, bo ciągły prefiks nigdy się nie ruszył. Opublikuj prefiks, gdy scheduler potwierdzi pełne pokrycie:

procedure TDownloadForm.CheckSignaturesWhenComplete;
var
  Report: TPadesValidationResult;
begin
  if FPdf.RangeRequests.IsRangeAvailable(0, FPdf.LogicalFileSize) then
    FPdf.AvailableByteCount := FPdf.LogicalFileSize;
  Report := FPdf.ValidatePades;
  if Report.SourceStatus = pvssIncomplete then
    LabelStatus.Caption := 'Signatures are checked when the download finishes'
  else
    ShowSignatureReport(Report);   // twoje UI
end;

Jeden limit rozmiaru obowiązuje, zanim cokolwiek z tego ruszy. Na Windows FPDF_FILEACCESS trzyma długość pliku w polu 32-bitowym, więc BeginProgressiveLoad odrzuca logiczny rozmiar powyżej 4 GiB przez EPdfError, zamiast pozwolić PDFium parsować uciętą długość

Ładowanie kompletnego lokalnego pliku na żądanie przez adapter strumienia opisuje strumieniowanie dużych PDF-ów na żądanie z PDFium; dla PDF-a siedzącego w większym buforze patrz ładowanie zakresów bajtów dla osadzonych PDF-ów. Zatrzymanie powolnego renderu strony, która już przybyła, to osobny mechanizm — omawia go anulowalne przyrostowe renderowanie stron. TPdfProgressiveDocument, jego scheduler zakresów i SaveAsLinearized są częścią PDFium Component dla Delphi i C++Buildera