From 8bcaa657b39f24f0f2457f5c28e7095d5113ba73 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Sun, 25 Oct 2026 11:20:38 -0300 Subject: pdfrender 4: docs/next-pdfrender.md: the design, MuPDF's threading rules as applied, the numbers on the SDM and the docs' PDF, positions --- docs/next-pdfrender.md | 257 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 docs/next-pdfrender.md (limited to 'docs') diff --git a/docs/next-pdfrender.md b/docs/next-pdfrender.md new file mode 100644 index 00000000..e006aa48 --- /dev/null +++ b/docs/next-pdfrender.md @@ -0,0 +1,257 @@ +# pdfrender: PDF pages rendered off the loop + +The author's ask: "add concurrency to the mupdf build so its smoother". The +open item of `next-anim.md` (7): the bridge rendered on the loop through one +MuPDF context and a one-page cache, so a PDF's first frame, a far jump's +page and every page a held PageDown reached cost the frame they landed in. +Later asks from the coordinator, answered here too: the Intel SDM (combined +volumes, 5363 pages, 27 MB) as the stress file with its own timedemo; the +page-size pass off the loop; a PDF's places on the jumplist. + +Positions, not a verdict: argue with them. + +## The change stack (workspace `pdfrender`, on main `nqmoxkwz`) + +| change | what | +|---|---| +| pdfrender 0 `ttsruwot` | the `pdf-sdm` timedemo (run where `sdm.pdf` is) and the probe's `landed` column: PDF rasters installed in a frame, on the loop or from a lane. The "before" binaries are built from this change | +| pdfrender 1 `vnpzkxnt` | pages render on lanes: locks, cloned contexts, a document a lane, jobs, generations, cookies, blanks, render-ahead, kept pages; the watch's double open and the far jump's text frame fixed | +| pdfrender 2 `owxvnlpw` | the page-size pass on a lane; MuPDF's page-tree map off | +| pdfrender 3 `swnnkynt` | a PDF's place on the jumplist: page and offset, Back lands on it, JumpScope file, a closed PDF reopens there | + +## MuPDF's threading rules, as applied + +MuPDF allows one thread at a time in an `fz_context` and one at a time in an +`fz_document`; contexts cloned from one made with `fz_locks_context` share +what is safe to share under its locks. + +| object | shared or per thread | +|---|---| +| base `fz_context` | the loop's own; made with `fz_locks_context` over `FZ_LOCK_MAX` pthread mutexes (in the base document struct), so it can be cloned. The loop clones a lane's context on the loop, from its own context | +| lane `fz_context` | one per lane (`fz_clone_context`), used by one job at a time on the lane's thread, dropped on the loop after the lane is joined | +| `fz_document` | **never shared**. The loop's document (text, search, selection, links, outline, the highlight pass) is the base's; each lane opens its OWN from the same bytes (`pardes_pdf_lane_open`, on its thread) | +| `fz_buffer` (the file's bytes) | shared, read only; its count kept and dropped under the alloc lock | +| store, glyph cache, fonts' context, colorspaces, document handlers | shared by the clones (MuPDF keeps them under `FZ_LOCK_ALLOC`, `FZ_LOCK_FREETYPE`, `FZ_LOCK_GLYPHCACHE`) | +| allocator | the shared C heap over `pdf_gpa` (the pdf region: a thread-safe DebugAllocator); MuPDF takes `FZ_LOCK_ALLOC` round every call anyway | +| `fz_cookie` | per job, in the `Job`; the loop sets `abort` (atomic store), MuPDF reads it at each operator | +| pixmap, device, page, display list | per job, made and dropped on the lane | + +So no `fz_context` or `fz_document` is ever touched by two threads: the +loop's are the loop's, a lane's are the lane's (one job at a time, handed +over through the job's future, whose await is the happens-before). The +test "two lanes render two pages of one document at once, each as the base +renders it, and a cookie aborts" renders pages 0 and 1 on two threads at +once and compares them byte for byte with the base's render. + +Why a document a lane rather than one document under a lock with display +lists handed out (MuPDF's `multi-threaded.c` pattern): with one document, +the loop's text, search, hover and selection would wait on the lock while a +lane records a page's display list (its content interpreted, ~half a render). +A document a lane costs one more parse a lane (40-60 ms RS on the SDM, on +the lane) and its own fonts. + +## The design as built + +- **Lanes** (`pdf_view.Lane`, two): `io.concurrent` jobs (`renderJob`), the + Stream pattern. `reconcile` asks; the loop never calls MuPDF to render + (banded pages, too tall for one buffer, stay on the loop as before). + `collect` takes what is done at the start of each reconcile, `land` swaps + the buffer into its slot (no pixel copied on the loop). `nextWake` asks for + frames while a lane works (as a picture's decode does). +- **Generations**: each slot records the job it waits for (`pending`); a job + lands only into the slot that waits for its generation. A request changed + (resize, fit, tint) or the page gone from the strip: the slot asks again or + is retired, and the old job's raster is dropped when it comes. `sweep` + sets the cookie of every job no slot waits for. Test: "off the loop: pages + land from lanes, a stale request's raster never lands, and a job nobody + waits for is aborted" (eight request changes raced against their jobs). +- **What a frame draws before its page lands**: the slot's previous raster + if it has one (any resolution: scaled by the placement), else the page's + paper where the page will be (a 1x1 tinted texel drawn the page's size). + Never a stall. A far jump's first frame used to fall back to the page's + extracted text when nothing was placed (9 ms RS, 110 ms Debug on the SDM, + shown for one frame); it now keeps the PDF's frame. +- **Ahead**: the page past the strip the way it last went joins the asked + span (one page, after the ones in view). With two lanes that is the bound. +- **Measure** moved to the lane: loading a page on the loop's document (its + links, its annotations) cost 6-7 ms a page of the SDM in Debug. +- **Cold lanes**: a lane's first job parses its document and loads fonts; two + cold lanes at once slowed each other (the SDM's first page 1.7 -> 2.5 s + Debug), so a lane starts once the one before it is warm. +- **Kept pages** (`keepPage`/`unkeep`): a closing State hands its whole, + unhighlighted rasters to a process-wide list; a second open or a Restore of + the same file (path, length, hash of its first and last 64 KiB) at the same + request and tint shows them on its first frame. Bound: 64 MiB and 16 pages, + the least recently kept evicted first; freed at the shell's end + (`dropKept`). Test: "kept pages: ... bounded in bytes, the oldest going + first". +- **Page sizes** (pdfrender 2): the strip is laid out on the first page's + size; the last lane's first job measures every page; when the sizes land + (and differ) the next draw lays the strip out again by page and offset at + the core's position and shifts the strip's drawn position by the same + amount, so a glide in progress carries on (a retarget, not a reset). A + one-size document never relayouts. **A Look at page 3000 during the pass** + lands at page 3000's top on the assumed layout; when the sizes land the + anchor is page 3000, offset 0, so it stays on that page, its pixels moved + with the layout and the glide still running. Test: "page sizes off the + loop: ...". +- **MuPDF's page-tree map is off** (`pdf_set_page_tree_cache(0)`, every + document): its first page lookup parsed every page object (735 ms Debug on + the SDM): that, not the 5363 sizes, was the open's stall and every lane's + slow first page. A lookup walks the tree by /Count now. +- **The watch's double open**: arming a PDF's watch reloaded it (the + generation for a PDF started null), so every open parsed the document + twice, two thirds of the SDM's open. It now compares the bytes on disk with + the ones the pane read (`sameBytes`, the key of the kept pages). +- **Unchanged, on the loop, as the latency notes designed them**: the + highlight repaint (the clean copy kept by the lane's job, MuPDF's highlight + pass over the dirty rows on the loop's document), hover, selection, links, + text and search. The lane bakes a job's highlights the way a loop render + did; highlights that changed while it ran are repainted from its clean copy + when it lands. +- **Pictures** keep their thread (anim 7): one decode, no generations or + cancel to share, and moving it onto the lanes would not make it smaller. + +## The jumplist (pdfrender 3) + +A PDF's jump (`Loc.pdf`) is its page (`line`) and how far down it the strip +stands (`col`, a fraction of the page in 2^-32), and its path's hash. A +fraction rather than pixels: a zoom, a fit change or a resize scales every +page, and the fraction lands on the same print. Places are the same visit +when they stand within a body of each other on the strip (the text rule), so +a held PageDown or a wheel is one entry that follows the view, and two +places on one page more than a body apart are two. Back and Forward move the +core there at once and the strip follows through the motion system (a far +one as one body's slide, the page rendered where it comes to rest); a place +the strip already stands on (half a pixel is the fraction's rounding) is not +moved. JumpScope file keeps to the PDF. A closed PDF's entries stay while +Recent knows it and a step onto one reopens it at the page and fraction. +The Jumplist pane prints a PDF's entry as `path:page`. Tests: "a PDF's jumps: +Back after a far jump returns to the exact offset, two places on one page are +two entries" (the SDM when the machine has it, else the docs' PDF), "a PDF's +jumps: JumpScope file keeps to the PDF, and a closed PDF reopens at its +place". Before: `line = page + 1, col = 0, path_hash = 0`, compared in rows, +so every jump within a body's count of PAGES was one entry, scope file +treated a PDF as no file, a closed PDF could not reopen, and Back landed on a +page's top. + +## Numbers + +Headless (`SDL_VIDEO_DRIVER=offscreen`, 1280x900, `.scratch/tools/demo.sh`, +`an.py`): this offscreen SDL presents **in software**, so the present is the +frame's tail in both builds (a software GPU wait of 10-30 ms now and then) +and the lanes compete with it for CPU. The column that is the render's is +*core work* (update + render). Pairs run back to back, base (main + the +demo, `ttsruwot`) then after; round 1 shown, round 2 within a ms or two +everywhere but the present tails (`.scratch/runs/final/`). ms +p50/p90/p99/max; *gap* is the present gap of frames something moved into; +*jank* counts those over 1.5 periods (period 16 ms here); *landed* is the +frames a page landed in. The open's numbers are from the Look's input: the +open runs in the shell's wait, before the frame's marks. + +### Intel SDM (`pdf-sdm`) + +| | open -> first frame | open -> first page | +|---|---|---| +| Debug before | 2123 ms (one frame of 1286) | 2123 | +| Debug after | 97 | 458 | +| RS before | 198 (one of 113) | 198 | +| RS after | 80 | 160 | + +| Debug | phase | core work | frame work | gap (moving) | jank | landed | landed frame work p50/max | +|---|---|---|---|---|---|---|---| +| before | spin | 0.8/0.9/39.7/55.9 | 4.5/8.6/49.4/59.2 | 12.6/17.1/49.6/63.6 | 2 | 2 | 59.2/59.2 | +| after | spin | 0.9/1.1/1.4/1.5 | 5.4/9.3/11.7/13.0 | 11.7/17.6/21.3/21.7 | 0 | 2 | 11.7/11.7 | +| before | held PageDown 5 s | 0.8/34.3/83.0/86.1 | 6.3/38.7/87.0/92.2 | 15.2/42.9/93.3/94.4 | 45 | 44 | 52.7/92.2 | +| after | held PageDown 5 s | 0.8/1.0/1.3/1.5 | 4.9/10.0/16.2/18.0 | 14.9/19.3/23.1/27.0 | 3 | 44 | 4.8/11.2 | +| before | far jump (Look :3000, Back, gg) | 1.1/1.5/52.2/52.2 | 5.6/9.2/59.1/59.1 | 15.9/19.1/20.6/20.6 | 0 | 1 | 59.1/59.1 | +| after | far jump | 0.9/1.1/2.1/2.1 | 4.5/9.5/12.6/12.6 | 16.3/18.9/21.3/21.3 | 0 | 2 | 12.6/12.6 | +| before | slow notches | 0.8/1.1/1.5/37.6 | 4.7/7.0/10.9/53.9 | 16.0/17.6/20.9/22.1 | 0 | 1 | 53.9/53.9 | +| after | slow notches | 0.8/1.0/1.2/1.5 | 4.6/5.6/8.5/12.5 | 16.2/17.2/19.0/23.7 | 0 | 2 | 12.5/12.5 | +| before | whole run | | | 15.5/21.4/88.4/94.4 | 47 of 567 | | | +| after | whole run | | | 15.3/18.9/22.8/27.0 | 3 of 803 | | | + +| RS | phase | core work | frame work | gap (moving) | jank | landed | landed frame work | +|---|---|---|---|---|---|---|---| +| before | spin | 0.1/0.2/8.3/9.1 | 3.4/7.7/14.7/18.1 | 11.9/16.8/19.2/20.3 | 0 | 2 | 18.1/18.1 | +| after | spin | 0.1/0.2/0.3/2.0 | 3.1/7.8/9.3/9.3 | 11.7/16.6/20.1/20.4 | 0 | 2 | 8.7/8.7 | +| before | held PageDown | 0.1/5.1/9.3/11.0 | 3.7/10.5/16.6/20.0 | 14.7/20.8/29.1/30.1 | 9 | 44 | 11.2/20.0 | +| after | held PageDown | 0.1/0.2/0.2/0.3 | 3.5/8.5/14.4/14.7 | 15.3/20.2/23.2/27.9 | 2 | 44 | 4.2/8.3 | +| before | far jump | 0.2/0.3/6.2/6.2 | 3.6/5.2/14.3/14.3 | 16.2/16.9/17.3/17.3 | 0 | 1 | 9.3/9.3 | +| after | far jump | 0.2/0.2/2.9/2.9 | 3.5/7.3/14.3/14.3 | 16.4/20.1/27.6/27.6 | 1 | 2 | 14.3/14.3 | +| before | slow notches | 0.1/0.2/0.2/7.1 | 3.9/6.2/7.7/23.4 | 16.4/16.9/17.2/17.3 | 0 | 1 | 23.4/23.4 | +| after | slow notches | 0.1/0.2/0.2/0.2 | 3.8/7.6/8.1/8.2 | 16.5/17.1/20.5/20.7 | 0 | 1 | 8.2/8.2 | +| before | whole run | | | 15.6/18.3/24.7/30.1 | 9 of 725 | | | +| after | whole run | | | 15.7/18.9/23.1/29.0 | 4 of 747 | | | + +The far-jump phase does more after: Back used to do nothing on a PDF +(Ctrl-o found no entry), so "after" also slides back from page 3000 and +renders it. The landed frame's remaining cost is the present's upload of the +new texture (12.8 MB at this size); the core's part of it is under 0.3 ms. + +### docs/design.pdf (`pdf-scroll`) + +| | open -> first frame | open -> first page | +|---|---|---| +| Debug before / after | 167 / 10 ms | 167 / 313 | +| RS before / after | 38 / 7 | 38 / 67 | + +| | phase | Debug core work | Debug gap | RS core work | RS gap | +|---|---|---|---|---|---| +| before | spin | 0.8/0.9/1.2/139.3 | 12.0/17.1/20.6/147.8 | 0.1/0.2/0.3/22.1 | 11.0/17.0/21.5/33.1 | +| after | spin | 0.8/1.0/1.3/1.7 | 11.6/16.7/21.4/22.3 | 0.2/0.3/0.4/1.9 | 11.5/17.6/21.4/21.5 | +| before | held PageDown | 0.8/128.9/166.1/166.1 | 16.3/133.8/175.8/175.8 | 0.2/0.6/34.5/34.5 | 15.1/22.3/40.5/40.5 | +| after | held PageDown | 0.9/1.1/1.4/1.4 | 15.3/20.5/24.8/24.8 | 0.1/0.2/0.3/0.3 | 15.7/19.0/22.9/22.9 | +| before | far jump | 0.9/1.2/78.5/78.5 | 16.4/18.0/20.0/20.0 | 0.2/0.3/16.5/16.5 | 16.0/19.9/21.7/21.7 | +| after | far jump | 0.9/1.4/2.1/2.1 | 16.3/19.9/27.1/27.1 | 0.2/0.3/2.4/2.4 | 16.3/20.1/21.9/21.9 | +| before | whole run, jank | 7 of 299 | | 5 of 348 | | +| after | whole run, jank | 5 of 441 | | 1 of 439 | | + +The first page of the small PDF lands later than before in Debug (313 vs +167 ms): the lane's parse and cold fonts, against the old open that rendered +it inside a frozen 162 ms frame. The window is up and moving 10 ms after the +Look. + +## Tests + +`mupdf-check` (25, the lanes test among them); unit filters `PDF`, `pdf`, +`off the loop`, `kept pages`, `page sizes off the loop`, `watch`, +`JumpScope`, `Back`, `jump`, `Jump`, `Recent`, `a PDF's jumps`: green. The +snapshot suite (`zig build snap -Dplatform=tty`): all 110 scripts. The tty +compiles (the suite builds it). The two baseline failures were not run. + +## Open questions and positions + +1. **The open itself is still on the loop**: reading the file, MuPDF's open + (the xref), and the watch's re-read to compare bytes: 75-95 ms on the SDM + in both builds. Position: open the base document on a lane too, the pane + appearing at once with its tag and paper; it is the next stall. +2. **Two lanes, a document each**: the price is one parse a lane and each + lane's own fonts (memory, and a cold first page per lane). Position: keep + it; a shared document behind a lock would make the loop's text, search and + hover wait on a lane. +3. **Lanes compete with a software present** (this headless run): the + present gap's tail moved within the noise, but on a CPU-starved machine + the lanes could take the present's core. The `io.concurrent` threads are + the pool's, so they cannot be niced without leaving the pool thread niced. + Position: leave it; on the author's GPU present it does not arise. +4. **The jumplist's tolerance**: asked "within a few rows' worth"; built + "within a body", the text's rule. With a few rows, every PageDown and + every PageDown held would be a jump of its own. Two places on one page a + body apart are still two entries. The entry follows the wheel (a PDF has + no cursor to stay behind), so Back after wheeling far and a `gg` returns + to where the wheel left you, where a text returns to its cursor. +5. **A far jump's slide** starts a body short of its pages and shows paper + there: the old page is not kept for the slide. Position: keep (as anim's + position 5). +6. **The highlight pass and hover stay on the loop's document**: a hover on a + page the loop has not loaded loads it there (6-7 ms Debug on the SDM). + Position: fine for now; it is the pointer's own frame, not a scroll's. +7. **Recent keeps a file by the path it was opened as**: a PDF (or a text) + opened by a relative path and closed does not reopen from the jumplist + when the Look from another pane resolves it differently (found writing the + test, not changed). +8. ponytail ceilings in the code: two lanes; one page ahead; the blank's + texture keyed revision 0 (a tint change shows the old paper until the page + lands); the kept pages' file key (path, length, first and last 64 KiB); + failed sizes pass keeps the assumed sizes. -- cgit v1.3