1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
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.
|