Oxicloud/benches/BASELINE.md

Thumbnail performance — Phase 0 baseline

Phase 1.1 (shrink-on-load) is now merged — see "Phase 1.1 results" at the bottom for the before/after. The tables below remain the Phase 0 baseline (the "before").

The "before" numbers every later phase must beat. Captured on 14 cores with the current image 0.25 pipeline (render_thumbnail_from_data / render_all_thumbnails_from_data in src/infrastructure/services/thumbnail_service.rs).

Heap = logical allocation high-water mark (counting allocator), not RSS. The synthetic corpus is high-entropy (gradient + noise), so JPEG sizes and decode work are realistic-to-slightly-pessimistic. Drop real photos into benches/corpus/ (same filenames) to re-baseline on real data.

Reproduce

# Peak RAM + saturated throughput (Task 0.3) → target/bench-baseline-fase0.json
cargo run --release --features bench --example bench_thumbnails_mem

# Per-size latency + output bytes (Task 0.2) → target/criterion/report/index.html
cargo bench --features bench           # do NOT pipe through `tail` — it truncates the log;
                                       # results are saved under target/criterion/ regardless

A. Per-image — peak heap, single-thread latency, output size

case	fmt	source	MP	render_all ms	peak heap MB	out KB (3 sizes)
jpeg_12mp	jpeg	4000×3000	12.0	111.30	96.1	57
jpeg_24mp	jpeg	6000×4000	24.0	207.23	151.0	41
jpeg_48mp	jpeg	8000×6000	48.0	397.67	260.9	38
jpeg_exif_orient	jpeg	4000×3000	12.0	121.82	107.6	59
png_large	png	3000×2000	6.0	34.36	58.4	63
webp_large	webp	1280×853	1.1	21.05	20.7	113
gif_large	gif	600×600	0.4	12.86	15.4	232
small_300	jpeg	300×300	0.1	9.94	8.0	184

B. Saturated throughput (14 threads, 3 s window)

case	source	MP	photos/sec	eff ms/photo
jpeg_12mp	4000×3000	12.0	44.4	22.52
jpeg_24mp	6000×4000	24.0	25.3	39.51
jpeg_48mp	8000×6000	48.0	12.4	80.49

Scaling is sub-linear (14 threads ≈ 4.9× single-thread): memory-bandwidth bound (moving 96–261 MB per decode) + rayon oversubscription (each caller thread fans 3 sizes onto the shared rayon pool).

C. Per-size latency — criterion median ms (one size in isolation vs all-three)

case	Icon ms	Preview ms	Large ms	all-3 ms	Large/all
jpeg_12mp	75.42	97.17	106.30	107.11	99.3%
jpeg_24mp	148.65	190.05	200.70	203.44	98.7%
jpeg_48mp	303.31	375.33	386.04	391.24	98.7%
jpeg_exif_orient	90.68	122.57	119.27	119.33	100.0%
png_large	13.32	25.87	32.26	32.59	99.0%
webp_large	15.83	19.51	24.47	24.45	100.1%
gif_large	2.28	5.15	12.94	12.92	100.2%
small_300	0.85	3.22	9.94	9.92	100.2%

Key findings (these steer Phase 1)

1. Decode dominates: 70–99 % of total time. For jpeg_12mp, rendering all three sizes (107 ms) costs barely more than rendering Icon alone (75 ms) — the full-resolution decode is the shared cost; per-size resize+encode is cheap on top. ⇒ Shrink-on-load (Task 1.1) is the single biggest lever, bigger than first estimated.

2. Peak heap scales linearly with megapixels (~2× the RGBA bitmap): 12 MP→96 MB, 48 MP→261 MB. With the real cpus/2 semaphore that is up to 7×261 MB ≈ 1.8 GB on a 48 MP burst — the OOM ceiling that caps concurrency. Shrink-on-load collapses this ~16× and unlocks Task 1.5 (raise the semaphore).

3. Task 2.1 "defer Large" is now DROPPED — the benchmark refutes it. Because all three sizes share one decode (Large/all ≈ 99 %), deferring Large saves ~9 ms eager but forces a second full decode (~106 ms) when the lightbox opens — it roughly doubles total decode work. Keep generating all sizes in one pass.

4. No-upscale (Task 1.4) confirmed minor: small_300's Large (9.9 ms) upscales 300→800; clamping recovers a few ms and avoids artefacts.

5. PNG/GIF/WebP get no DCT shrink-on-load — only fast_image_resize (Task 1.2) speeds their resize portion.

---

Phase 1.1 results — shrink-on-load (DCT scale-on-decode for JPEG)

Implemented via jpeg-decoder in decode_oriented / decode_jpeg_scaled (src/infrastructure/services/thumbnail_service.rs). The JPEG decoder now emits the image at the smallest DCT scale (1/8·1/4·1/2·1/1) whose long axis is still ≥ the largest needed thumbnail (800 px), so the full-resolution bitmap is never materialised. Non-JPEG and unusual JPEG colour spaces fall back to a full decode. Same machine (14 cores), same corpus.

Latency — render_all, single thread (ms)

case	before	after	speedup
jpeg_12mp	111.30	60.64	1.84×
jpeg_24mp	207.23	113.71	1.82×
jpeg_48mp	397.67	202.88	1.96×
jpeg_exif	121.82	60.12	2.03×
png_large	34.36	33.67	~1× (no DCT, expected)

Peak heap per decode (MB) — the headline win

case	before	after	reduction
jpeg_12mp	96.1	17.6	5.5×
jpeg_24mp	151.0	24.9	6.1×
jpeg_48mp	260.9	17.6	14.8×
jpeg_exif	107.6	18.9	5.7×

Peak heap is now decoupled from source resolution (~18–25 MB regardless of MP — bounded by the 800 px decode, not the original). 48 MP now uses less than 24 MP because it hits the 1/8 scale (1000×750) vs 24 MP's 1/4 (1500×1000).

Saturated throughput (14 threads, photos/sec)

case	before	after	speedup
jpeg_12mp	44.4	140.8	3.17×
jpeg_24mp	25.3	74.7	2.95×
jpeg_48mp	12.4	45.3	3.65×

Throughput improved more than single-thread latency (3.2× vs 1.8× at 12 MP): parallel efficiency rose from ~4.9× to ~8.5× across 14 threads because the 16× smaller decode buffers relieve the memory-bandwidth ceiling.

Quality gate — shrink-on-load vs full decode (Preview 400 px)

case	SSIM	PSNR dB
jpeg_12mp	0.9875	47.42
jpeg_24mp	0.9927	48.91
jpeg_48mp	0.9939	49.37
small_300	0.9995	55.17

All SSIM ≥ 0.98 (acceptance criterion met) and PSNR 47–55 dB (>40 dB = visually indistinguishable). Output bytes unchanged (e.g. 12 MP: 57→58 KB).

Follow-ups this unlocked

• Task 1.5 (raise cpus/2 → cpus): peak heap no longer scales with MP, so the OOM ceiling that justified halving concurrency is largely gone. ✅ done below.
• The MAX_DECODE_PIXELS 50 MP reject could be relaxed — huge JPEGs now decode cheaply at 1/8 — but that is a behaviour change, deferred.

---

Phase 1.5 results — raise decode-concurrency cap (cpus/2 → cpus)

max_concurrent_decodes() now defaults to all cores (was half), overridable via OXICLOUD_THUMBNAIL_DECODE_CONCURRENCY. Safe only because Phase 1.1 decoupled peak heap from source resolution.

Measured with a harness that mirrors the real service path (Table D: tokio::Semaphore(permits) + spawn_blocking, many concurrent requests), 14 cores, 3 s window:

case	7 permits (cpus/2, old)	14 permits (cpus, new)	28 (cpus*2)
jpeg_12mp	92.7	133.7 (1.44×)	133.3 (—)
jpeg_24mp	49.5	69.9 (1.41×)	71.1 (+1.7%)

• ~1.4× throughput on the real path, for free; peak heap unchanged (17–25 MB).
• cpus*2 yields nothing → cpus is the right ceiling for CPU-bound work.
• It's 1.4× not 2× because render_all fans its 3 sizes onto rayon, so 7 permits already partly fill all cores — the remaining headroom is Task 1.7 (rayon oversubscription).

---

Phase 1.2 results — SIMD resize (fast_image_resize, Lanczos3)

Replaced the image crate's scalar resampler with fast_image_resize (AVX2/SSE4.1/NEON) in the shared encode_thumbnail helper; render_all now converts to RGB8 once and SIMD-resizes the shared buffer per size. Lanczos3 for downscaling, CatmullRom when upscaling (avoids Lanczos ringing). Also folded the duplicated path-variant generate_all_sizes_background into the shared render path, so it too gets shrink-on-load + SIMD. "before" = post-1.5 state.

Single-thread latency render_all (ms) and peak heap (MB)

case	ms before	ms after	speedup	heap before	heap after
jpeg_12mp	60.89	56.46	1.08×	17.6	7.1
jpeg_24mp	113.98	106.76	1.07×	24.9	10.1
jpeg_48mp	203.29	198.75	1.02×	17.6	7.1
png_large	33.63	12.92	2.60×	58.4	27.1
gif_large	12.93	7.99	1.62×	15.4	5.9
webp_large	21.15	16.89	1.25×	20.7	8.3
small_300	10.64	6.37	1.67×	8.0	3.9

• JPEG: only ~6–8 % — shrink-on-load already shrank the decoded bitmap, so the resize was a small slice of the time. But peak heap fell another ~2.5× (7 MB): fir works on tight RGB buffers with no intermediate DynamicImage, and RGB conversion now happens once instead of per size.
• PNG: 2.6× (and GIF/WebP 1.25–1.6×) — exactly as predicted: these decode at full resolution (no DCT shrink), so the SIMD resize dominates the win.

Throughput (≈ +10–15 %, run-to-run noisy)

Saturated 12 MP ≈ 142→157 photos/s; semaphore-bounded 12 MP @ 14 permits ≈ 134→148. Directionally up; treat as noise-bounded.

Quality gate (vs full-decode CatmullRom at identical dims)

case	SSIM	PSNR dB
jpeg_12mp	0.9865	47.21
jpeg_24mp	0.9923	48.73
jpeg_48mp	0.9938	49.33
small_300	0.9921	42.59

All ≥ 0.98. (The upscale case small_300 needed the Lanczos3→CatmullRom upscale rule — Lanczos rings when enlarging; it was 0.954 before that fix.)

Note

Output thumbnails are now exactly max_dim on the long side (e.g. 400×266), vs the old image::resize fit-within which produced 399×266 — a ≤1 px change, invisible under the frontend's object-fit: cover.

---

Phase 1.7 — TESTED AND REVERTED (rayon oversubscription)

Hypothesis: render_all's internal par_iter over the 3 sizes oversubscribes the global rayon pool under load (cpus×3 tasks), capping burst throughput. Tested by resizing the 3 sizes sequentially (parallelism across images only). Measured before/after on 14 cores, two runs each:

metric	before (par_iter)	after (sequential)	verdict
PNG single-image latency	12.9 ms	21.3 ms	−66 % WORSE
JPEG 12 MP single-image	57.8 ms	58.5 ms	neutral
Saturated 12 MP (photos/s)	155.8	170 / 158	flat (noise)
Semaphore @14 12 MP	157.7	164 / 157	flat
Semaphore @28 12 MP	160.4	162 / 159	flat

Verdict: reverted. Throughput at the real operating point (14 permits) is flat — rayon oversubscription was not the bottleneck. The "1.4× not 2×" of Phase 1.5 is the single-threaded JPEG decode (which dominates post-shrink) plus memory bandwidth, not rayon scheduling; even 28 concurrent renders (84 rayon tasks) show no thrash. Meanwhile full-decode formats (PNG) regressed 66 % on single-image latency because their resize-from-full-resolution genuinely benefits from the per-image parallelism. Net negative → kept par_iter.

(Another "measure before believing" result, like the dropped Task 2.1.)