summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-pdfrender.md257
1 files changed, 257 insertions, 0 deletions
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.