vizmatic 0.8.3 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/PROMPT.md +32 -0
- package/README.md +8 -3
- package/ROADMAP.md +4 -2
- package/SCIENCE.md +69 -3
- package/dist/chunk-6JI55YX4.js +604 -0
- package/dist/{chunk-LTX44BAE.js → chunk-BYKXNUX7.js} +25 -4
- package/dist/{chunk-4MXGLMBG.js → chunk-EPZLNABN.js} +107 -37
- package/dist/chunk-EWCO6ZT6.js +696 -0
- package/dist/{chunk-JZPMGVBP.js → chunk-G7HRSKHV.js} +1 -1
- package/dist/{chunk-RPAHMKAR.js → chunk-JTWC2OPN.js} +7 -5
- package/dist/chunk-LJZO36IR.js +124 -0
- package/dist/chunk-REL2BZ2B.js +88 -0
- package/dist/chunk-RLPEOWST.js +1 -0
- package/dist/chunk-VMHOWCDL.js +296 -0
- package/dist/chunk-YDD63HHD.js +1 -0
- package/dist/{chunk-I745F4QK.js → chunk-YNGDEARY.js} +1134 -643
- package/dist/cli.js +80 -543
- package/dist/gpu-selection-CDWCZH27.js +1 -0
- package/dist/gpu-selection-MX6NHMNA.js +635 -0
- package/dist/index.cjs +473 -155
- package/dist/index.d.cts +30 -239
- package/dist/index.d.ts +30 -239
- package/dist/index.js +410 -457
- package/dist/math-E7W5LFWO.js +1 -0
- package/dist/{math-LXB4FH4E.js → math-NEFQUPRV.js} +3 -1
- package/dist/scene-browser.js +17 -17
- package/dist/scene-cli.js +1 -1
- package/dist/scene-runtime.cjs +4 -2
- package/dist/scene-runtime.js +2 -2
- package/dist/stage-browser/browser.d.ts +1206 -854
- package/dist/stage-browser/gpu-renderer.js +138 -0
- package/dist/stage-browser/{math-4WFNHVV2.js → math-KYHUOK7A.js} +46 -10
- package/dist/stage-browser/stage.js +107 -19
- package/dist/stage-export.cjs +8221 -6784
- package/dist/stage-export.d.cts +13 -5
- package/dist/stage-export.d.ts +13 -5
- package/dist/stage-export.js +111 -601
- package/dist/stage.cjs +6243 -3474
- package/dist/stage.d.cts +1064 -765
- package/dist/stage.d.ts +1064 -765
- package/dist/stage.js +3571 -2405
- package/dist/{svg-import-B5BGbC1t.d.cts → svg-import-CSCFWYaB.d.cts} +21 -12
- package/dist/{svg-import-B5BGbC1t.d.ts → svg-import-CSCFWYaB.d.ts} +21 -12
- package/dist/teaching-math-DTKc0XsB.d.cts +243 -0
- package/dist/teaching-math-ydDBhJ2M.d.ts +243 -0
- package/dist/{video-CiN1MDCS.d.cts → theme-DhVdDQKO.d.cts} +4 -237
- package/dist/{video-CiN1MDCS.d.ts → theme-DhVdDQKO.d.ts} +4 -237
- package/dist/video-BYCeOz8F.d.ts +259 -0
- package/dist/video-CGLxJXqu.d.cts +259 -0
- package/examples/catalog-science-physics.tsx +6 -6
- package/examples/films/_boltzmann-entropy/model.ts +63 -0
- package/examples/films/_catalysis/model.ts +49 -0
- package/examples/films/_gravitational-waves/model.ts +32 -0
- package/examples/films/_heat-equation/model.ts +54 -0
- package/examples/films/_hydrogen-orbitals/model.ts +31 -0
- package/examples/films/_maxwell/model.ts +84 -0
- package/examples/films/_planetary-orbits/appearance.ts +71 -0
- package/examples/films/_planetary-orbits/model.ts +152 -0
- package/examples/films/_planetary-orbits/saturn.ts +142 -0
- package/examples/films/_quantum-tunneling/model.ts +58 -0
- package/examples/films/_reaction-diffusion/model.ts +61 -0
- package/examples/films/_stationary-action/model.ts +38 -0
- package/examples/films/attention.ts +309 -253
- package/examples/films/beam-search.ts +321 -49
- package/examples/films/boltzmann-entropy.ts +104 -0
- package/examples/films/cache-miss.ts +387 -394
- package/examples/films/catalog.json +238 -77
- package/examples/films/catalysis.ts +128 -0
- package/examples/films/central-limit.ts +27 -22
- package/examples/films/complex-maps.ts +70 -56
- package/examples/films/deck-example.ts +261 -200
- package/examples/films/euler-circle.ts +72 -28
- package/examples/films/flash-attention.ts +549 -0
- package/examples/films/forecast.ts +2 -2
- package/examples/films/fourier-epicycles.ts +21 -20
- package/examples/films/gradient-descent.ts +23 -49
- package/examples/films/gravitational-waves.ts +179 -0
- package/examples/films/heat-equation.ts +124 -0
- package/examples/films/hydrogen-orbitals.ts +135 -0
- package/examples/films/io-uring.ts +635 -0
- package/examples/films/linear-maps.ts +42 -31
- package/examples/films/lorenz.ts +42 -79
- package/examples/films/maxwell.ts +197 -0
- package/examples/films/pathlines.ts +85 -0
- package/examples/films/planetary-orbits.ts +146 -0
- package/examples/films/pythagoras.ts +18 -10
- package/examples/films/quantum-tunneling.ts +116 -0
- package/examples/films/rag-citations.ts +423 -0
- package/examples/films/reaction-diffusion.ts +70 -0
- package/examples/films/ring-allreduce.ts +531 -0
- package/examples/films/stationary-action.ts +170 -0
- package/examples/films/svd-3d.ts +605 -0
- package/examples/films/taylor-series.ts +9 -9
- package/examples/films/vizmatic-title.ts +1 -0
- package/examples/vizmatic-hero.tsx +102 -32
- package/package.json +3 -1
- package/dist/chunk-3F2VQ7NW.js +0 -1
- package/dist/chunk-GGFDBJ25.js +0 -88
- package/dist/math-QVCETQDQ.js +0 -1
|
@@ -0,0 +1,635 @@
|
|
|
1
|
+
import {
|
|
2
|
+
Box,
|
|
3
|
+
assertEqual,
|
|
4
|
+
barChart,
|
|
5
|
+
boundary,
|
|
6
|
+
column,
|
|
7
|
+
connector,
|
|
8
|
+
countUp,
|
|
9
|
+
counter,
|
|
10
|
+
crossThrough,
|
|
11
|
+
delay,
|
|
12
|
+
dot,
|
|
13
|
+
draw,
|
|
14
|
+
fadeIn,
|
|
15
|
+
fadeOut,
|
|
16
|
+
film,
|
|
17
|
+
fitted,
|
|
18
|
+
infoBox,
|
|
19
|
+
lagged,
|
|
20
|
+
lanes,
|
|
21
|
+
morphMatching,
|
|
22
|
+
par,
|
|
23
|
+
pictogram,
|
|
24
|
+
place,
|
|
25
|
+
ringBuffer,
|
|
26
|
+
row,
|
|
27
|
+
sceneKit,
|
|
28
|
+
spotlight,
|
|
29
|
+
surroundingBox,
|
|
30
|
+
text,
|
|
31
|
+
} from 'vizmatic/stage'
|
|
32
|
+
|
|
33
|
+
// Ring ownership and acquire/release ordering: https://man7.org/linux/man-pages/man7/io_uring.7.html
|
|
34
|
+
// SQPOLL may sleep and require a wakeup syscall: IORING_SETUP_SQPOLL in
|
|
35
|
+
// https://man7.org/linux/man-pages/man2/io_uring_setup.2.html
|
|
36
|
+
// Timelines are illustrative. Final counts exclude setup, waits, and wakeups.
|
|
37
|
+
export default film(
|
|
38
|
+
{
|
|
39
|
+
title: 'io_uring: shared rings, fewer syscalls',
|
|
40
|
+
description:
|
|
41
|
+
'Blocking reads enter and leave the kernel individually. io_uring shares submission and completion rings with the kernel: batch requests into one enter call, or submit without one while an SQPOLL thread stays awake.',
|
|
42
|
+
look: 'midnight',
|
|
43
|
+
font: 'text-serif',
|
|
44
|
+
fps: 60,
|
|
45
|
+
poster: 22.8,
|
|
46
|
+
},
|
|
47
|
+
(s) => {
|
|
48
|
+
const kit = sceneKit({ size: 38 })
|
|
49
|
+
const title = kit.heading('io_uring: shared rings, fewer syscalls')
|
|
50
|
+
s.add(title)
|
|
51
|
+
|
|
52
|
+
// Leave comfortable bottom clearance for captions across all 4 chapters.
|
|
53
|
+
const stageArea = new Box(
|
|
54
|
+
kit.area.left + 8,
|
|
55
|
+
kit.area.top + 2,
|
|
56
|
+
kit.area.right - 8,
|
|
57
|
+
kit.area.bottom - 26,
|
|
58
|
+
)
|
|
59
|
+
const [tagRowBox, stageBox] = stageArea.rows([0.07, 0.93], 12)
|
|
60
|
+
|
|
61
|
+
const ch1Tag = text('Chapter 1: Every read crosses the wall', {
|
|
62
|
+
size: 28,
|
|
63
|
+
weight: 600,
|
|
64
|
+
color: 'orange',
|
|
65
|
+
})
|
|
66
|
+
const ch2Tag = text('Chapter 2: Two rings in shared memory', {
|
|
67
|
+
size: 28,
|
|
68
|
+
weight: 600,
|
|
69
|
+
color: 'blue',
|
|
70
|
+
})
|
|
71
|
+
const ch3Tag = text('Chapter 3: Submit in batches, reap without trapping', {
|
|
72
|
+
size: 28,
|
|
73
|
+
weight: 600,
|
|
74
|
+
color: 'teal',
|
|
75
|
+
})
|
|
76
|
+
const ch4Tag = text('Chapter 4: Fewer submission syscalls', {
|
|
77
|
+
size: 28,
|
|
78
|
+
weight: 600,
|
|
79
|
+
color: 'green',
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
for (const tag of [ch1Tag, ch2Tag, ch3Tag, ch4Tag]) {
|
|
83
|
+
place(tag, tagRowBox, 'left')
|
|
84
|
+
}
|
|
85
|
+
s.add(ch1Tag.hide())
|
|
86
|
+
|
|
87
|
+
// =========================================================================
|
|
88
|
+
// Chapter 1: Every read crosses the wall
|
|
89
|
+
// =========================================================================
|
|
90
|
+
const [ch1LeftPane, ch1RightPane] = stageBox.columns([1.04, 1], 40)
|
|
91
|
+
const [ch1TopBox, ch1LanesBox] = ch1RightPane.rows([0.24, 0.76], 16)
|
|
92
|
+
|
|
93
|
+
const switchCounter = counter(0, {
|
|
94
|
+
suffix: ' mode switches',
|
|
95
|
+
size: 34,
|
|
96
|
+
weight: 700,
|
|
97
|
+
color: 'orange',
|
|
98
|
+
})
|
|
99
|
+
const readNote = text('8 blocking pread calls (2 mode switches each)', {
|
|
100
|
+
size: 27,
|
|
101
|
+
color: 'dim',
|
|
102
|
+
})
|
|
103
|
+
place(
|
|
104
|
+
column([switchCounter, readNote], { gap: 10, align: 'left' }),
|
|
105
|
+
ch1TopBox,
|
|
106
|
+
'left',
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
const wallWidth = Math.round(ch1LeftPane.width - 16)
|
|
110
|
+
const syscallWall = boundary({
|
|
111
|
+
width: wallWidth,
|
|
112
|
+
label: 'privilege wall (ring 3 <-> ring 0)',
|
|
113
|
+
above: 'user space',
|
|
114
|
+
below: 'kernel VFS',
|
|
115
|
+
color: 'orange',
|
|
116
|
+
weight: 4.5,
|
|
117
|
+
tally: 'syscalls',
|
|
118
|
+
size: 27,
|
|
119
|
+
}).at(ch1LeftPane.cx, ch1LeftPane.top + ch1LeftPane.height * 0.34)
|
|
120
|
+
|
|
121
|
+
const driverWall = boundary({
|
|
122
|
+
width: wallWidth,
|
|
123
|
+
label: 'block queue <-> NVMe IRQ',
|
|
124
|
+
below: 'NVMe SSD',
|
|
125
|
+
color: 'blue',
|
|
126
|
+
weight: 3,
|
|
127
|
+
dash: true,
|
|
128
|
+
tally: 'IRQs',
|
|
129
|
+
size: 27,
|
|
130
|
+
}).at(ch1LeftPane.cx, ch1LeftPane.top + ch1LeftPane.height * 0.74)
|
|
131
|
+
|
|
132
|
+
const blockingEvents = Array.from({ length: 8 }, (_, i) => {
|
|
133
|
+
const base = i * 12
|
|
134
|
+
return [
|
|
135
|
+
{ lane: 'App thread', start: base, end: base + 2.2, color: 'blue' as const },
|
|
136
|
+
{
|
|
137
|
+
lane: 'App thread',
|
|
138
|
+
start: base + 2.2,
|
|
139
|
+
end: base + 11.4,
|
|
140
|
+
color: 'red' as const,
|
|
141
|
+
label: i === 0 ? 'stall' : undefined,
|
|
142
|
+
},
|
|
143
|
+
{ lane: 'Kernel VFS', start: base + 2.2, end: base + 5.0, color: 'orange' as const },
|
|
144
|
+
{ lane: 'NVMe SSD', start: base + 5.0, end: base + 9.6, color: 'teal' as const },
|
|
145
|
+
{ lane: 'Kernel VFS', start: base + 9.6, end: base + 11.4, color: 'orange' as const },
|
|
146
|
+
]
|
|
147
|
+
}).flat()
|
|
148
|
+
|
|
149
|
+
const ch1Lanes = fitted(ch1LanesBox, (width) =>
|
|
150
|
+
lanes(['App thread', 'Kernel VFS', 'NVMe SSD'], blockingEvents, {
|
|
151
|
+
width,
|
|
152
|
+
barHeight: 42,
|
|
153
|
+
size: 27,
|
|
154
|
+
domain: [0, 96],
|
|
155
|
+
axisLabel: 'Illustrative blocking schedule; not measured time',
|
|
156
|
+
}),
|
|
157
|
+
)
|
|
158
|
+
place(ch1Lanes, ch1LanesBox, 'center')
|
|
159
|
+
|
|
160
|
+
s.add(
|
|
161
|
+
readNote.hide(),
|
|
162
|
+
switchCounter.hide(),
|
|
163
|
+
syscallWall.hide(),
|
|
164
|
+
driverWall.hide(),
|
|
165
|
+
ch1Lanes.hide(),
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
s.chapter('Every read crosses the wall')
|
|
169
|
+
s.caption(
|
|
170
|
+
'Each blocking read enters the kernel and returns to user space: 8 calls make 16 privilege transitions.',
|
|
171
|
+
10.4,
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
s.play(
|
|
175
|
+
par(
|
|
176
|
+
fadeIn(ch1Tag, { duration: 0.7 }),
|
|
177
|
+
fadeIn(readNote, { duration: 0.75 }),
|
|
178
|
+
fadeIn(switchCounter, { duration: 0.75 }),
|
|
179
|
+
),
|
|
180
|
+
)
|
|
181
|
+
s.play(
|
|
182
|
+
par(
|
|
183
|
+
syscallWall.enter({ duration: 0.95 }),
|
|
184
|
+
driverWall.enter({ duration: 0.95 }),
|
|
185
|
+
ch1Lanes.enter({ duration: 0.95 }),
|
|
186
|
+
),
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
const crossings = Array.from({ length: 8 }, (_, i) => {
|
|
190
|
+
const xPos = syscallWall.x((i + 0.5) / 8)
|
|
191
|
+
return crossThrough([syscallWall, driverWall], xPos, {
|
|
192
|
+
direction: 'round',
|
|
193
|
+
reach: 44,
|
|
194
|
+
color: 'orange',
|
|
195
|
+
duration: 0.95,
|
|
196
|
+
})
|
|
197
|
+
})
|
|
198
|
+
const sweepDuration = 5.4
|
|
199
|
+
s.play(
|
|
200
|
+
par(
|
|
201
|
+
lagged(crossings, { lag: 0.55, duration: sweepDuration }),
|
|
202
|
+
countUp(switchCounter, 16, { duration: sweepDuration }),
|
|
203
|
+
ch1Lanes.showAll({ duration: sweepDuration }),
|
|
204
|
+
),
|
|
205
|
+
)
|
|
206
|
+
assertEqual(syscallWall.count, 8, 'blocking syscalls counted')
|
|
207
|
+
assertEqual(driverWall.count, 8, 'driver IRQ trips counted')
|
|
208
|
+
s.wait(3.2)
|
|
209
|
+
|
|
210
|
+
s.play(
|
|
211
|
+
fadeOut([readNote, switchCounter, syscallWall, driverWall, ch1Lanes], {
|
|
212
|
+
duration: 0.65,
|
|
213
|
+
}),
|
|
214
|
+
)
|
|
215
|
+
|
|
216
|
+
// =========================================================================
|
|
217
|
+
// Chapter 2: Two rings in shared memory
|
|
218
|
+
// =========================================================================
|
|
219
|
+
const [appColBox, ringsCenterBox, kernelColBox] = stageBox.columns(
|
|
220
|
+
[0.175, 0.65, 0.175],
|
|
221
|
+
20,
|
|
222
|
+
)
|
|
223
|
+
const [sharedTitleBox, wheelsBox, ringStatusBox] = ringsCenterBox.rows(
|
|
224
|
+
[0.11, 0.77, 0.12],
|
|
225
|
+
10,
|
|
226
|
+
)
|
|
227
|
+
|
|
228
|
+
const sharedHeader = text('mmap() shared memory (visible to user + kernel)', {
|
|
229
|
+
size: 28,
|
|
230
|
+
weight: 600,
|
|
231
|
+
color: 'blue',
|
|
232
|
+
})
|
|
233
|
+
place(sharedHeader, sharedTitleBox, 'center')
|
|
234
|
+
|
|
235
|
+
const sq = ringBuffer(8, {
|
|
236
|
+
radius: 142,
|
|
237
|
+
thickness: 58,
|
|
238
|
+
color: 'blue',
|
|
239
|
+
label: 'Submission Queue',
|
|
240
|
+
size: 27,
|
|
241
|
+
labelSize: 27,
|
|
242
|
+
headColor: 'purple',
|
|
243
|
+
tailColor: 'blue',
|
|
244
|
+
tailFollows: 'publish',
|
|
245
|
+
counts: true,
|
|
246
|
+
})
|
|
247
|
+
|
|
248
|
+
const cq = ringBuffer(8, {
|
|
249
|
+
radius: 142,
|
|
250
|
+
thickness: 58,
|
|
251
|
+
color: 'teal',
|
|
252
|
+
label: 'Completion Queue',
|
|
253
|
+
size: 27,
|
|
254
|
+
labelSize: 27,
|
|
255
|
+
headColor: 'teal',
|
|
256
|
+
tailColor: 'green',
|
|
257
|
+
tailFollows: 'publish',
|
|
258
|
+
counts: true,
|
|
259
|
+
})
|
|
260
|
+
|
|
261
|
+
const wheelsRow = row([sq, cq], { gap: 28, align: 'center' })
|
|
262
|
+
place(wheelsRow, wheelsBox, 'center')
|
|
263
|
+
|
|
264
|
+
const sharedFrame = surroundingBox([sq, cq], {
|
|
265
|
+
pad: 14,
|
|
266
|
+
radius: 14,
|
|
267
|
+
color: 'blue',
|
|
268
|
+
width: 2,
|
|
269
|
+
fill: 'blue',
|
|
270
|
+
fillOpacity: 0.05,
|
|
271
|
+
})
|
|
272
|
+
|
|
273
|
+
const ringInvariantNote = text(
|
|
274
|
+
'Producer release-stores tail; consumer acquire-loads tail',
|
|
275
|
+
{ size: 27, color: 'dim' },
|
|
276
|
+
)
|
|
277
|
+
place(ringInvariantNote, ringStatusBox, 'center')
|
|
278
|
+
|
|
279
|
+
const appIcon = pictogram('process', { size: 60, color: 'blue', accent: 'teal' })
|
|
280
|
+
const appCard = infoBox({
|
|
281
|
+
title: 'User App',
|
|
282
|
+
rows: [
|
|
283
|
+
{ label: 'SQ', value: 'push', tone: 'blue' },
|
|
284
|
+
{ label: 'CQ', value: 'reap', tone: 'teal' },
|
|
285
|
+
],
|
|
286
|
+
accent: 'blue',
|
|
287
|
+
size: 27,
|
|
288
|
+
})
|
|
289
|
+
place(column([appIcon, appCard], { gap: 14, align: 'center' }), appColBox, 'center')
|
|
290
|
+
|
|
291
|
+
const kernelIcon = pictogram('process', { size: 64, color: 'teal', accent: 'yellow' })
|
|
292
|
+
const kernelCard = infoBox({
|
|
293
|
+
title: 'Kernel',
|
|
294
|
+
rows: [
|
|
295
|
+
{ label: 'SQ', value: 'poll', tone: 'purple' },
|
|
296
|
+
{ label: 'CQ', value: 'post', tone: 'green' },
|
|
297
|
+
],
|
|
298
|
+
accent: 'teal',
|
|
299
|
+
size: 27,
|
|
300
|
+
})
|
|
301
|
+
place(column([kernelIcon, kernelCard], { gap: 14, align: 'center' }), kernelColBox, 'center')
|
|
302
|
+
|
|
303
|
+
const appToSq = connector(appCard, sharedFrame, {
|
|
304
|
+
from: 'right',
|
|
305
|
+
to: 'left',
|
|
306
|
+
fromOffset: -0.28,
|
|
307
|
+
toOffset: -0.22,
|
|
308
|
+
color: 'blue',
|
|
309
|
+
width: 2.5,
|
|
310
|
+
curvature: 0.25,
|
|
311
|
+
})
|
|
312
|
+
const cqToApp = connector(sharedFrame, appCard, {
|
|
313
|
+
from: 'left',
|
|
314
|
+
to: 'right',
|
|
315
|
+
fromOffset: 0.22,
|
|
316
|
+
toOffset: 0.28,
|
|
317
|
+
color: 'teal',
|
|
318
|
+
width: 2.5,
|
|
319
|
+
curvature: 0.25,
|
|
320
|
+
})
|
|
321
|
+
const sqToKernel = connector(sharedFrame, kernelCard, {
|
|
322
|
+
from: 'right',
|
|
323
|
+
to: 'left',
|
|
324
|
+
fromOffset: -0.22,
|
|
325
|
+
toOffset: -0.28,
|
|
326
|
+
color: 'purple',
|
|
327
|
+
width: 2.5,
|
|
328
|
+
dash: [7, 6],
|
|
329
|
+
flow: 46,
|
|
330
|
+
curvature: 0.25,
|
|
331
|
+
})
|
|
332
|
+
const kernelToCq = connector(kernelCard, sharedFrame, {
|
|
333
|
+
from: 'left',
|
|
334
|
+
to: 'right',
|
|
335
|
+
fromOffset: 0.28,
|
|
336
|
+
toOffset: 0.22,
|
|
337
|
+
color: 'green',
|
|
338
|
+
width: 2.5,
|
|
339
|
+
dash: [7, 6],
|
|
340
|
+
flow: 46,
|
|
341
|
+
curvature: 0.25,
|
|
342
|
+
})
|
|
343
|
+
|
|
344
|
+
const sqDots = Array.from({ length: 4 }, () => dot(9, 'yellow').hide())
|
|
345
|
+
const cqDots = Array.from({ length: 4 }, () => dot(9, 'green').hide())
|
|
346
|
+
|
|
347
|
+
s.add(
|
|
348
|
+
sharedFrame.hide(),
|
|
349
|
+
sharedHeader.hide(),
|
|
350
|
+
sq.hide(),
|
|
351
|
+
cq.hide(),
|
|
352
|
+
ringInvariantNote.hide(),
|
|
353
|
+
appIcon.hide(),
|
|
354
|
+
appCard.hide(),
|
|
355
|
+
kernelIcon.hide(),
|
|
356
|
+
kernelCard.hide(),
|
|
357
|
+
appToSq.hide(),
|
|
358
|
+
sqToKernel.hide(),
|
|
359
|
+
kernelToCq.hide(),
|
|
360
|
+
cqToApp.hide(),
|
|
361
|
+
...sqDots,
|
|
362
|
+
...cqDots,
|
|
363
|
+
)
|
|
364
|
+
|
|
365
|
+
s.chapter('Two rings in shared memory')
|
|
366
|
+
s.caption(
|
|
367
|
+
'io_uring shares submission and completion rings between user space and the kernel. Here, an awake SQPOLL thread consumes submissions.',
|
|
368
|
+
9.4,
|
|
369
|
+
)
|
|
370
|
+
|
|
371
|
+
s.play(
|
|
372
|
+
par(
|
|
373
|
+
morphMatching(ch1Tag, ch2Tag, { duration: 0.7 }),
|
|
374
|
+
fadeIn(sharedFrame, { duration: 0.85 }),
|
|
375
|
+
fadeIn(sharedHeader, { duration: 0.85 }),
|
|
376
|
+
sq.enter({ duration: 1.15 }),
|
|
377
|
+
cq.enter({ duration: 1.15 }),
|
|
378
|
+
),
|
|
379
|
+
)
|
|
380
|
+
s.play(
|
|
381
|
+
par(
|
|
382
|
+
fadeIn([appIcon, appCard, kernelIcon, kernelCard], { duration: 0.85 }),
|
|
383
|
+
fadeIn(ringInvariantNote, { duration: 0.85 }),
|
|
384
|
+
draw(appToSq, { duration: 0.9 }),
|
|
385
|
+
draw(sqToKernel, { duration: 0.9 }),
|
|
386
|
+
draw(kernelToCq, { duration: 0.9 }),
|
|
387
|
+
draw(cqToApp, { duration: 0.9 }),
|
|
388
|
+
),
|
|
389
|
+
)
|
|
390
|
+
s.wait(4.8)
|
|
391
|
+
|
|
392
|
+
// =========================================================================
|
|
393
|
+
// Chapter 3: Submit in batches, reap without trapping
|
|
394
|
+
// =========================================================================
|
|
395
|
+
const trapFreeNote = text(
|
|
396
|
+
'Awake SQPOLL: publish tail; kernel consumes SQ and posts CQ',
|
|
397
|
+
{ size: 27, weight: 600, color: 'teal' },
|
|
398
|
+
)
|
|
399
|
+
place(trapFreeNote, ringStatusBox, 'center')
|
|
400
|
+
s.add(trapFreeNote.hide())
|
|
401
|
+
|
|
402
|
+
s.chapter('Submit in batches, reap without trapping')
|
|
403
|
+
s.caption(
|
|
404
|
+
'Publish four SQEs with a release-store. The kernel acquire-loads tail, advances head, runs the I/O, and posts completions. User space drains CQ.',
|
|
405
|
+
12.8,
|
|
406
|
+
)
|
|
407
|
+
|
|
408
|
+
s.play(
|
|
409
|
+
par(
|
|
410
|
+
morphMatching(ch2Tag, ch3Tag, { duration: 0.7 }),
|
|
411
|
+
fadeOut(ringInvariantNote, { duration: 0.4 }),
|
|
412
|
+
delay(fadeIn(trapFreeNote, { duration: 0.55 }), 0.48),
|
|
413
|
+
),
|
|
414
|
+
)
|
|
415
|
+
|
|
416
|
+
s.play(
|
|
417
|
+
par(
|
|
418
|
+
lagged(
|
|
419
|
+
[
|
|
420
|
+
sq.push({ label: 'R0', color: 'blue', pending: true }, { duration: 0.58 }),
|
|
421
|
+
sq.push({ label: 'R1', color: 'blue', pending: true }, { duration: 0.58 }),
|
|
422
|
+
sq.push({ label: 'R2', color: 'blue', pending: true }, { duration: 0.58 }),
|
|
423
|
+
sq.push({ label: 'R3', color: 'blue', pending: true }, { duration: 0.58 }),
|
|
424
|
+
],
|
|
425
|
+
{ lag: 0.42 },
|
|
426
|
+
),
|
|
427
|
+
appToSq.pulse({ color: 'blue', duration: 1.3 }),
|
|
428
|
+
),
|
|
429
|
+
)
|
|
430
|
+
assertEqual(sq.pending, 4, '4 SQEs staged before publish')
|
|
431
|
+
assertEqual(sq.tail, 4, 'writer index advanced across 4 SQEs')
|
|
432
|
+
|
|
433
|
+
s.play(sq.publish({ duration: 0.95 }))
|
|
434
|
+
assertEqual(sq.pending, 0, '0 pending SQEs after atomic publish')
|
|
435
|
+
assertEqual(sq.length, 4, 'all 4 SQEs visible to kernel poller')
|
|
436
|
+
s.wait(1.4)
|
|
437
|
+
|
|
438
|
+
s.play(
|
|
439
|
+
par(
|
|
440
|
+
lagged(
|
|
441
|
+
[
|
|
442
|
+
sq.pop({ duration: 0.58 }),
|
|
443
|
+
sq.pop({ duration: 0.58 }),
|
|
444
|
+
sq.pop({ duration: 0.58 }),
|
|
445
|
+
sq.pop({ duration: 0.58 }),
|
|
446
|
+
],
|
|
447
|
+
{ lag: 0.42 },
|
|
448
|
+
),
|
|
449
|
+
lagged(
|
|
450
|
+
[
|
|
451
|
+
sqToKernel.send(sqDots[0]!, { duration: 0.68 }),
|
|
452
|
+
sqToKernel.send(sqDots[1]!, { duration: 0.68 }),
|
|
453
|
+
sqToKernel.send(sqDots[2]!, { duration: 0.68 }),
|
|
454
|
+
sqToKernel.send(sqDots[3]!, { duration: 0.68 }),
|
|
455
|
+
],
|
|
456
|
+
{ lag: 0.42 },
|
|
457
|
+
),
|
|
458
|
+
),
|
|
459
|
+
)
|
|
460
|
+
assertEqual(sq.head, 4, 'SQ head matches tail after kernel fetch')
|
|
461
|
+
assertEqual(sq.length, 0, 'SQ empty after kernel consumes submissions')
|
|
462
|
+
|
|
463
|
+
s.play(
|
|
464
|
+
par(
|
|
465
|
+
lagged(
|
|
466
|
+
[
|
|
467
|
+
kernelToCq.send(cqDots[0]!, { duration: 0.65 }),
|
|
468
|
+
kernelToCq.send(cqDots[1]!, { duration: 0.65 }),
|
|
469
|
+
kernelToCq.send(cqDots[2]!, { duration: 0.65 }),
|
|
470
|
+
kernelToCq.send(cqDots[3]!, { duration: 0.65 }),
|
|
471
|
+
],
|
|
472
|
+
{ lag: 0.4 },
|
|
473
|
+
),
|
|
474
|
+
lagged(
|
|
475
|
+
[
|
|
476
|
+
cq.push({ label: 'C0', color: 'teal', pending: true }, { duration: 0.55 }),
|
|
477
|
+
cq.push({ label: 'C1', color: 'teal', pending: true }, { duration: 0.55 }),
|
|
478
|
+
cq.push({ label: 'C2', color: 'teal', pending: true }, { duration: 0.55 }),
|
|
479
|
+
cq.push({ label: 'C3', color: 'teal', pending: true }, { duration: 0.55 }),
|
|
480
|
+
],
|
|
481
|
+
{ lag: 0.4 },
|
|
482
|
+
),
|
|
483
|
+
),
|
|
484
|
+
)
|
|
485
|
+
s.play(cq.publish({ duration: 0.85 }))
|
|
486
|
+
assertEqual(cq.tail, 4, 'CQ tail published to 4')
|
|
487
|
+
assertEqual(cq.length, 4, '4 CQEs ready for user space')
|
|
488
|
+
s.wait(1.3)
|
|
489
|
+
|
|
490
|
+
s.play(
|
|
491
|
+
par(
|
|
492
|
+
lagged(
|
|
493
|
+
[
|
|
494
|
+
cq.pop({ duration: 0.55 }),
|
|
495
|
+
cq.pop({ duration: 0.55 }),
|
|
496
|
+
cq.pop({ duration: 0.55 }),
|
|
497
|
+
cq.pop({ duration: 0.55 }),
|
|
498
|
+
],
|
|
499
|
+
{ lag: 0.4 },
|
|
500
|
+
),
|
|
501
|
+
cqToApp.pulse({ color: 'teal', duration: 1.15 }),
|
|
502
|
+
),
|
|
503
|
+
)
|
|
504
|
+
assertEqual(cq.head, 4, 'CQ head advances to 4 after user reap')
|
|
505
|
+
assertEqual(cq.length, 0, 'CQ cleanly drained')
|
|
506
|
+
s.wait(3.4)
|
|
507
|
+
|
|
508
|
+
s.play(
|
|
509
|
+
fadeOut(
|
|
510
|
+
[
|
|
511
|
+
sharedFrame,
|
|
512
|
+
sharedHeader,
|
|
513
|
+
sq,
|
|
514
|
+
cq,
|
|
515
|
+
trapFreeNote,
|
|
516
|
+
appIcon,
|
|
517
|
+
appCard,
|
|
518
|
+
kernelIcon,
|
|
519
|
+
kernelCard,
|
|
520
|
+
appToSq,
|
|
521
|
+
sqToKernel,
|
|
522
|
+
kernelToCq,
|
|
523
|
+
cqToApp,
|
|
524
|
+
],
|
|
525
|
+
{ duration: 0.65 },
|
|
526
|
+
),
|
|
527
|
+
)
|
|
528
|
+
|
|
529
|
+
// =========================================================================
|
|
530
|
+
// Chapter 4: Fewer submission syscalls
|
|
531
|
+
// =========================================================================
|
|
532
|
+
const [chartColBox, pipelineColBox] = stageBox.columns([0.48, 0.52], 32)
|
|
533
|
+
const [chartHeaderBox, chartBodyBox] = chartColBox.rows([0.13, 0.87], 12)
|
|
534
|
+
const [pipeLanesBox, payoffBox] = pipelineColBox.rows([0.64, 0.36], 18)
|
|
535
|
+
|
|
536
|
+
const chartHeading = text('Submission syscalls for 32 reads', {
|
|
537
|
+
size: 30,
|
|
538
|
+
weight: 600,
|
|
539
|
+
color: 'ink',
|
|
540
|
+
})
|
|
541
|
+
place(chartHeading, chartHeaderBox, 'center')
|
|
542
|
+
|
|
543
|
+
const submitChart = barChart(
|
|
544
|
+
[
|
|
545
|
+
{ label: 'Blocking', value: 32, color: 'orange' },
|
|
546
|
+
{ label: 'Batched', value: 1, color: 'blue' },
|
|
547
|
+
{ label: 'SQPOLL', value: 0, color: 'teal' },
|
|
548
|
+
],
|
|
549
|
+
{
|
|
550
|
+
width: Math.min(600, Math.round(chartBodyBox.width - 100)),
|
|
551
|
+
height: Math.min(370, Math.round(chartBodyBox.height - 90)),
|
|
552
|
+
labelSize: 28,
|
|
553
|
+
max: 32,
|
|
554
|
+
ticks: [0, 8, 16, 24, 32],
|
|
555
|
+
showValues: true,
|
|
556
|
+
states: true,
|
|
557
|
+
format: (v) => `${Math.round(v)}`,
|
|
558
|
+
},
|
|
559
|
+
)
|
|
560
|
+
place(submitChart, chartBodyBox, 'center')
|
|
561
|
+
|
|
562
|
+
const asyncEvents = [
|
|
563
|
+
{ lane: 'App thread', start: 0, end: 18, color: 'blue' as const, label: 'SQE x32' },
|
|
564
|
+
{ lane: 'App thread', start: 19, end: 46, color: 'teal' as const, label: 'compute' },
|
|
565
|
+
{ lane: 'App thread', start: 47, end: 64, color: 'blue' as const, label: 'SQE x32' },
|
|
566
|
+
{ lane: 'App thread', start: 65, end: 96, color: 'teal' as const, label: 'compute' },
|
|
567
|
+
{ lane: 'Kernel work', start: 4, end: 48, color: 'purple' as const },
|
|
568
|
+
{ lane: 'Kernel work', start: 50, end: 94, color: 'purple' as const },
|
|
569
|
+
{ lane: 'NVMe SSD', start: 6, end: 52, color: 'green' as const, label: 'depth 32' },
|
|
570
|
+
{ lane: 'NVMe SSD', start: 52, end: 96, color: 'green' as const, label: 'depth 32' },
|
|
571
|
+
]
|
|
572
|
+
const ch4Lanes = fitted(pipeLanesBox, (width) =>
|
|
573
|
+
lanes(['App thread', 'Kernel work', 'NVMe SSD'], asyncEvents, {
|
|
574
|
+
width,
|
|
575
|
+
barHeight: 44,
|
|
576
|
+
size: 27,
|
|
577
|
+
domain: [0, 96],
|
|
578
|
+
axisLabel: 'Illustrative overlap; SQPOLL thread stays awake',
|
|
579
|
+
}),
|
|
580
|
+
)
|
|
581
|
+
place(ch4Lanes, pipeLanesBox, 'center')
|
|
582
|
+
|
|
583
|
+
const payoffCard = infoBox({
|
|
584
|
+
title: 'Submission counts, not a speed benchmark',
|
|
585
|
+
rows: [
|
|
586
|
+
{ label: 'batch', value: '32 SQEs, 1 enter call', tone: 'blue' },
|
|
587
|
+
{ label: 'SQPOLL', value: '0 while poller is awake', tone: 'teal' },
|
|
588
|
+
{ label: 'excluded', value: 'setup, waits, wakeups', tone: 'dim' },
|
|
589
|
+
],
|
|
590
|
+
accent: 'green',
|
|
591
|
+
size: 27,
|
|
592
|
+
width: Math.min(760, Math.round(payoffBox.width - 16)),
|
|
593
|
+
})
|
|
594
|
+
place(payoffCard, payoffBox, 'center')
|
|
595
|
+
|
|
596
|
+
s.add(
|
|
597
|
+
chartHeading.hide(),
|
|
598
|
+
submitChart.hide(),
|
|
599
|
+
ch4Lanes.hide(),
|
|
600
|
+
payoffCard.hide(),
|
|
601
|
+
)
|
|
602
|
+
|
|
603
|
+
s.chapter('Fewer submission syscalls')
|
|
604
|
+
s.caption(
|
|
605
|
+
'A batch submits 32 reads with one enter call. Awake SQPOLL needs none; setup, blocking waits, and waking a sleeping poller still need syscalls.',
|
|
606
|
+
9.4,
|
|
607
|
+
)
|
|
608
|
+
|
|
609
|
+
s.play(
|
|
610
|
+
par(
|
|
611
|
+
morphMatching(ch3Tag, ch4Tag, { duration: 0.7 }),
|
|
612
|
+
fadeIn(chartHeading, { duration: 0.75 }),
|
|
613
|
+
submitChart.enter({ duration: 1.1 }),
|
|
614
|
+
ch4Lanes.enter({ duration: 0.95 }),
|
|
615
|
+
fadeIn(payoffCard, { duration: 0.95 }),
|
|
616
|
+
),
|
|
617
|
+
)
|
|
618
|
+
s.play(
|
|
619
|
+
par(
|
|
620
|
+
ch4Lanes.showAll({ duration: 2.6 }),
|
|
621
|
+
submitChart.mark('SQPOLL', 'chosen', { duration: 0.75 }),
|
|
622
|
+
),
|
|
623
|
+
)
|
|
624
|
+
s.play(
|
|
625
|
+
spotlight([submitChart, payoffCard], {
|
|
626
|
+
keep: [title, ch4Tag, chartHeading, ch4Lanes],
|
|
627
|
+
dim: 0.25,
|
|
628
|
+
duration: 0.9,
|
|
629
|
+
}),
|
|
630
|
+
)
|
|
631
|
+
s.wait(3.4)
|
|
632
|
+
s.play(spotlight(null, { duration: 0.75 }))
|
|
633
|
+
s.wait(2.8)
|
|
634
|
+
},
|
|
635
|
+
)
|