# 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=tui`): 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.