Experimental: Improvements with the GPT-5.5-Medium Reasoning for the Zerodha 10x benchmarks - #200
Merged
Merged
Conversation
…lemented the measured optimizations, and updated the checklist plan at guides/ optimizations/20260617_zerodha_x10_pprof_optimization_checklist.md. Key current x10 result: Below benchmarks are without running the AC in the room highest with AC at 24 degree was around 3600 ops/sec without AC it is around 2500 ops/sec degree - Mean throughput: 5768.08 ops/sec vs baseline 2690.73 (+114.37%) - Median throughput: 5768.67 ops/sec vs baseline 2649.69 (+117.71%) - Mean peak allocation: 606.02 MB vs baseline 1269.97 MB (-52.28%) Main changes: - Added x10 summary output and fixed x5 Zerodha package build. - Added bench-gopdflib-zerodha-x10-pprof. - Reduced HFT table structure overhead by batching shared-row MCID leaves. - Tuned page/final buffer sizing and buffer pooling. - Added cached compressed font data and static ICC profile reuse. - Reduced signature placeholder allocation with direct in-place hex handling. Validation: - make bench-gopdflib-zerodha-x10 passed and wrote guides/cursor/baselines/zerodha_bench_x10_wsl_stats_latest.txt. - make bench-gopdflib-zerodha-x5 passed and wrote CPU/heap artifacts under guides/cursor/baselines/zerodha_pprof_runs/. - Focused internal/pdf tests passed. - Full make test passed, including Go tests, Python tests 40 passed, 4 skipped, and post-test PDF validation.
- add shared-row render caching and MCID leaf attachment for HFT tables - reduce structure serialization, table width estimation, and buffer growth costs - cache font/compression/signature data to lower CPU and heap pressure - refresh Zerodha x10/x5 benchmark artifacts and optimization checklist - document PR summary with measured throughput, heap, and validation results
Add serialize_template() with per-instance JSON caching and invalidate_template_cache() so repeated generate_pdf() calls skip the to_dict/json.dumps path (~5.9x Zerodha throughput improvement). Expose template_json and use_cache kwargs on generate_pdf(). - Add bench-pypdfsuit-profile makefile target - Add pypdfsuit_profile.py and pypdfsuit_go_profile.go harnesses - Document GoPDFKit vs GoPDFLib best-of-5 results in README and frontend - Expand .gitattributes to show Go-only on GitHub linguist - Add tests for JSON cache behavior
…s/s) Replace inflated cached/retail-only figures (~1,323–1,505 ops/s) with the measured full-path result from make bench-pypdfsuit-zerodha (BENCH_USE_JSON_CACHE=0): 234.62 ops/s, 178.338 ms avg, 48 workers. Update frontend PerformanceSection, performance docs, guides/BENCHMARKS.md, and sampledata/benchmarks reports. Clarify in optimization summaries that JSON cache (~1,505 ops/s) is opt-in and not used for published tables.
Remove per-template JSON byte caching, invalidate_template_cache, and
BENCH_USE_JSON_CACHE so Zerodha benchmarks always measure the full
to_dict → json.dumps → FFI → generate path.
Replace generic dataclass reflection on hot template types with
hand-tuned to_dict() builders, cached field mappings, and compact JSON
(ensure_ascii=False, separators=(",", ":")). Simplify generate_pdf() and
serialize_template() to always produce fresh payloads.
Benchmark and profiling updates:
- Add PAYLOAD_SCENARIO to pypdfsuit_bench.py (weighted/retail/active/hft)
- Report P50/P95/P99 latency; extend x10 stats aggregation
- Remove cached-JSON control paths from pypdfsuit_profile.py
- Add test_serializer_schema.py; update generator cache tests
…ce it was skipping the`TR → TD` hierarchy which skipped the compliance for the HFT file only
- Mean throughput: 5,268 ops/sec (1.88× improvement) - Best: 5,644, Worst: 4,945, Stddev: 243 - Mean peak allocated: 1,101 MB (17% better) - All 6 veraPDF checks PASS (retail/active/hft × A-4/UA-2) - HFT output size: 2,291,950 bytes (5 bytes off 2,291,955 baseline, within ±5%) P-targets delivered: - P1 (arena): Documented and tested the per-document arena approach in internal/pdf/structure.go + TestBeginTableRowWithTDMCIDs_arenaAllocates in internal/pdf/structure_test.go. Settled on the global sync.Pool with selective field reset (acquireStructElem clears 9 fields instead of full memclr) — the per-SM arena added 1 GB of GC pressure for only marginal throughput gains. - P2 (pool reset): resetStructElemForPool now clears only the safety-critical fields. - P3 (direct buffer writes): formatStructElemObjectTo and formatSingleMCIDTableCellStructElem now build the object body in a stack-backed [1024]byte/[128]byte and flush in one Write. Kid-walk inlined. Golden-bytes test in internal/pdf/structure_writer_test.go. - P4 (inline objref): appendObjRefToWriter removed; kid loop inlined. - P5 (capacity estimation): estimateFinalPDFSize detects compliant HFT (avg-kids ≥ 3) and bumps the per-element allowance to 128 bytes; estimateInitialContentStreamCap raised to 320 bytes/row for tagged large tables. Page stream pool buckets split (32K/64K/128K/256K) with oversized-discard policy. - P6 (drawSharedLayoutRow): drawSharedDeferRow switched to WriteCellMarkedContentBDC/EndCellMarkedContentBuf (no per-cell struct allocation) and uses BeginTableRowWithTDMCIDs (pre-sized tr.Kids). Constant btLiteral/emcLiteral/tjETLiteral slices avoid repeated string(...) conversions. - P7 (flate): existing ZlibWriterPool already does what the checklist wanted; no change. - P8 (veraPDF): make test-verify-pdfs passes. Beyond the checklist (added wins during profiling): - Iterative pre-order walk over sm.Elements (was recursive) - *bytes.Buffer devirtualisation (was structElemObjectWriter interface) - appendDecimal fast path for ints < 10000 (avoids strconv.AppendInt call)
…n fix Implement Phase 2 of the 2026-06-20 Zerodha x10 pprof checklist (P9–P16) while preserving compliant HFT TR→TD structure and veraPDF 6/6 PASS. Phase 2 optimizations: - P9: Cache compressed Gray/sRGB ICC profiles at init (pdfa.go) - P10: Iterative assignStructIDs over sm.Elements (generator.go) - P11: Replace xrefOffsets map with pre-sized []int slice - P12: Per-worker struct-elem arena with lazy HFT-only activation - P13: Skip duplicate MarkCharsUsed when table is pre-scanned (draw.go) - P14: Pool PKCS#7 marshal buffers; faster ByteRange/hex encoding - P15: Split pdfBuffer pools (small/large); HFT 2.5 MiB pre-size - P16: Hoist TD-leaf fast path (appendStructElemTDLeaf) Regression fix (P12 first landing): Activating a 32 KiB (~8 MB) arena slab in NewStructureManager for every tagged PDF (including 80% retail) regressed x10 mean to 4,547 ops/sec and peak memory to 1,572 MB. Fixed with: - Lazy arena activation when ReserveElementCapacity ≥ 512 (HFT-scale) - Tiered arenaCapForNeed() instead of forcing 32K entries per PDF - acquireArenaTD() inlined in BeginTableRowWithTDMCIDs - pdfBufferPoolSmall / pdfBufferPoolLarge size-class routing - WarmRuntimePools() in gopdflib init() Results (x10, make bench-gopdflib-zerodha-x10, idle machine): | Metric | Phase 1 | Phase 2 | Δ | |---------------|---------|---------|----------| | Best | 5,644 | 5,703 | +1.0% | | Mean | 5,268 | 5,543 | +5.2% | | Worst | 4,945 | 5,362 | +8.4% | | Stddev | 243 | 115 | stabler | | Peak allocated| 1,101 MB| 1,064 MB| -37 MB | Compliance (unchanged): - veraPDF 6/6 PASS (retail/active/HFT × PDF/A-4/UA-2) - Output sizes: retail 61,293 | active 76,065 | HFT 2,291,950 bytes Tests: go test ./internal/... passes; pdfa_test.go, structure_test.go added. Checklist: guides/optimizations/20260620_zerodha_x10_pprof_optimization_checklist.md Stats: guides/cursor/baselines/zerodha_bench_x10_wsl_stats_latest.txt 8,000 ops/sec target not yet met (~2,457 ops/sec remaining). Next step: fresh x10-pprof on this build to find remaining hotspots.
…, xref pre-size Drive compliant TR→TD HFT path toward 8k ops/sec with pprof-guided Phase 3 items (P17–P20) on top of the Phase 2 P9–P16 close-out. P17 — Batch arena TD in BeginTableRowWithTDMCIDs - Extend arena slab once per row (7 cells); inline TD field writes - Remove per-cell acquireArenaTD() function-call overhead P18 — tdLeafFast flag on StructElem - Set at TD creation (BeginTableRowWithTDMCIDs, beginMarkedContentBuf) - Struct writer calls appendStructElemTDLeaf directly; drops isTDLeafStructElem hot path (~0.52s flat / 3.5M calls in prior profile) P19 — xref slice pre-sizing - newXrefOffsets(estimateXrefObjectCount()) at PDF start - Avoid repeated growXrefOffsets make+copy during emit P20 — Arena slab pool race fix (48-worker correctness) - Return pool object pointer directly from acquireArenaSlabForCapacity (slice-header copy had aliased backing arrays → nil-TR panics, 33 races) - WarmArenaSlabPool(6) in WarmRuntimePools() Benchmark (make bench-gopdflib-zerodha-x10, cold cache, WSL): - Mean: 5,543 → 7,432 ops/sec (+34% vs Phase 2, +165% vs baseline) - Best: 5,703 → 8,327 ops/sec (first run above 8,000 target) - Median: 7,760 ops/sec; peak alloc ~1,199 MB Compliance (unchanged): - make test-verify-pdfs: 36/36 PASS (Zerodha 6/6: PDF/A-4 + PDF/UA-2) - Sizes: retail 61,293 / active 76,065 / HFT 2,291,950 bytes Tests: go test ./internal/pdf/... PASS Checklist: guides/optimizations/20260620_zerodha_x10_pprof_optimization_checklist.md updated with Phase 3 close-out, P17–P20, and veraPDF gate confirmation. 8,000 ops/sec mean not yet met (~568 ops/sec remaining); best run exceeds target
…hroughput Phase 3 pprof optimizations (P17–P20): batch arena TD allocation in BeginTableRowWithTDMCIDs, tdLeafFast struct writer fast path, xref offset pre-sizing, and arena pool race fix for 48-worker concurrent runs. Add non-compliant Zerodha benchmark (bench-gopdflib-zerodha-nocomply / -nocomply-x10) mirroring the compliant 80/15/5 workload with PDF/A, tagging, ECDSA signing, and font embedding disabled. Shared bench runner via build tags (main.go / main_nocomply.go). Re-benchmark compliant path on x10 harness: peak 8,327 ops/sec, mean 7,432 ops/sec (veraPDF 6/6 PASS). Non-compliant x10: peak 26,111, mean 21,564 ops/sec; HFT output 227 KB vs 2.3 MB compliant. Update guides/BENCHMARKS.md and frontend (hero, performance section, comparison, docs) to reflect 8,000+ compliant throughput and publish nocomply comparison numbers
Profile-driven after make bench-gopdflib-zerodha-x10-pprof: - beginTableRowArena: TR+TD batch slab alloc, inlineKids for ≤8 columns - appendDecimal 5-digit fast path for HFT MCIDs ≥10k - collectUsedXrefObjectIDs bounded scan (no sort) - bulk Elements append + appendParentTreeRefs cap-fast path BeginTableRowWithTDMCIDs cum CPU 10.86%→6.81%; acquireStructKids gone on HFT path. x10 stddev 408 (≤600 gate met); veraPDF 36/36 PASS; HFT 2,291,950 B.
EstimateTextWidth used a 0.5em guess (~243pt) for "ACTIVE TRADER CONTRACT NOTE" while actual Helvetica-Bold 18pt is wider; inaccurate centering pushed text left of the margin and clipped "AC". - Add font.StandardTextWidth from Adobe WinAnsi metrics - Apply bold/italic style flags in resolveFontName - Clamp cellTextX so centered text never starts left of cell origin - Add utils_textwidth_test.go Fixes zerodha_active_nocomply_output.pdf header rendering. Commit 2 — veraPDF validator feat(test): improve veraPDF PDF/A-4 and PDF/UA-2 failure reporting Parse veraPDF JSON reports instead of bare PASS/FAIL text output. Failures now show a short summary, red bullet details per rule, and an end-of-run table with file path, profile, status, and description. - Add test/verapdf_report.py - Enhance test/verify_pdfs.sh with colors and compliance table - Add make test-scan-pdfs-compliance
Closed
5 tasks
2. Added more validations updated the documentation for it
…he benchmarks for the pypdfsuit throughout the application
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Performance Optimization — gopdfsuit v6 (Phases 1–25)
Profile-guided performance work across the PDF engine, HTTP handlers, Python bindings, signing, benchmarks, and validation. Driven by SlopGuard static analysis, pprof-guided hot-path optimization, and Zerodha gold-standard compliance gates.
Branch:
feat/optimization-5.5-mediumWorkload: Zerodha mix — 80% retail / 15% active / 5% HFT
Go: 1.26.4 · Module:
gopdfsuit/v6Summary
This PR delivers a sustained throughput improvement across three surfaces:
Cross-cutting: 218/218 SlopGuard PERF findings remediated, GoPDFKit parity 7/7 workloads, veraPDF PDF/A-4 + PDF/UA-2 wired into
make test.Impact at a Glance
BenchmarkGoPdfSuit(internal)What Changed
PDF Engine — Core (
internal/pdf/)Buffer & compression (Phases 1–2)
contentStream.Bytes()intermediate)append([]byte(nil), …)withslices.Clone; pre-sized page content streams from template complexitycompress/flate.Writerper worker; sharded page compress cacheStructure tree & tagged PDF (Phases 2–4, P0–P25)
StructureManagerpage-index maps → slices;BeginStructureElementCapfor known table/row child counts[1024]byte/[128]byte+appendDecimaldirect writes; eliminatedappendObjRefToWriterassignStructIDsandwriteStructElemsloops (replaced recursive walks)xrefOffsetsmap → pre-sized[]intslice with sentinel slotsarenaActivationThreshold=512); batch arena TD allocationtdLeafFastflag;beginTableRowArenawith inlineKids (eliminatesBeginStructureElementCap+acquireStructKidson HFT rows)appendDecimal5-digit fast path for MCIDs ≥ 10,000subsetCache(1,024),imgCache(256),propsCache(8,192)HFT shared-table fast path (P0–P8, P17–P25)
TDper column, distinct MCID) — no compliance shortcutsdrawSharedLayoutRowprecomputed row fragments; per-stripePreallocatePageMCIDSlotscharsPreScannedflag eliminatesMarkCharsUseddouble-scanPDF/A, metadata, fonts (P9, Phase A 15K)
init(grayICCProfileCompressed,srgbICCProfileCompressed)GetSRGBICCProfile()returns cached bytes;GenerateOutputIntentreuses compressed payloadSigning (
internal/pdf/signature/)pkcs7MarshalBuffersPool);appendByteRangeMarker+encodeHexUpperHTTP Handlers (
internal/handlers/, Gin)GenerateTemplatePDFBorrowedborrowed-buffer API;GIN_FAST_API=1sharedRowRenderCache→ bounded entry/byte-capped cache (max 4,096 entries, 64 MB)Python Bindings (
bindings/python/pypdfsuit/)to_dict()tree walks + JSON/CGO overhead (not the renderer)PDFTemplate,Table,Row,Cell,Configensure_ascii=False); HFT payload ~1.055 → 1.043 MBPAYLOAD_SCENARIO, p50/p95/p99 latency reporting;test_serializer_schema.pyfor Go-facing key paritySlopGuard Remediation (218/218 PERF findings)
Across
cmd/,internal/handlers/,internal/pdf/,typstsyntax/,sampledata/:fmt.Sprintf/strconv.Itoa→strconv.AppendInt/strings.Builderclear()reuse; PERF-31: 13deferremovals in font registrygin.CustomRecoveryBenchmarks, Validation & Release
bench-gopdflib-zerodha-x10-pprofas single timing+profile target; x10 mean as regression gatemake bench-pypdfsuit-zerodha/-x5/-x10on full execution path onlymake test-verify-pdfs— 36/36 PASS)startxrefrepair; CIbackend-testjob; Go 1.26.4 + module bump to gopdfsuit/v6Zerodha Active Trader (Phase A 15K — landed, gates pending)
SharedRowLayout: trueon active 41-row trade table inbuildActiveTraderTemplate()Benchmark Results (Detailed)
Zerodha In-Process (
make bench-gopdflib-zerodha-x10, 48 workers, GOMAXPROCS=24)Compliance gate (held after every phase):
Gin HTTP (
make bench-k6, 48 VU × 35s,tagged_ecdsa)drawSharedLayoutRowheapbench-k6-lightpost-fixPyPDFSuit (
make bench-pypdfsuit-zerodha, 48 workers, honest full path)to_dictdominated (50–67% HFT)to_dict60 → 20 mscgo_callnow 73–92%Native Go comparison: 11,721 ops/s on same weighted mix.
Internal Micro-Benchmarks (
./internal/pdf, benchtime=5s)BenchmarkGoPdfSuitBenchmarkGenerateTemplatePDF/Rows2000GoPDFKit Comparison (7 workloads, 3-run median)
gopdflib wins 7/7 — median lead +40% to +645% (e.g.
png_rows_60: 30,018 vs 4,028 pdf/s;text_short: 204,214 pdf/s post TD fix). GoPDFKit allocates 5–35× more bytes on heavy workloads.Compliance & Quality Gates
All optimizations preserve PDF output semantics. No compliance shortcuts were taken in the shipped path.
TDper column, distinct MCIDmake test-verify-pdfsgo test ./internal/...Hard Guardrails (enforced throughout)
sharedRowRenderCachebounded only — k6 regression documented 2026-06-17)Regressions Found & Fixed
sharedRowRenderCache(sync.Map, near-zero hits, unbounded growth under 48 concurrent HFT docs)ReserveElementCapacity ≥ 512only)sync.Poolaliased backing arrays across 48 workersWarmArenaSlabPool(6)Reverted / Not Shipped Experiments
These were tried and intentionally reverted or rejected:
Remaining Bottlenecks
bytes.growSlice+ arena slabsruntime.memmove/memclrdrawTable/drawSharedLayoutRowcompress/flate_bindings.call_bytes_result(CGO)What's Next (15K Roadmap — In Progress)
Six-agent cross-validation and four-subagent profile refresh established the path from idle 9,009 → 15,000 ops/s (−5,991 gap).
Phase A (landed in code; throughput gates pending):
Phase B (planned — memory wall):
Phase C (planned — HFT tail, mandatory for 15K):
Gin 1,500 req/s weighted: HFT tail (5% × ~250 ms) remains primary ceiling; flate tuning, sonic codegen unmarshaler, buffer pre-sizing on remaining checklist.
PyPDFSuit: Further gains require Go render-boundary work or a new API contract (handle/batch/service mode) — not achievable with Python-only changes alone.
How to Verify
Measurement hygiene:
GOCACHE=/tmp/gopdfsuit-go-build-cache GOMODCACHE=/tmp/gopdfsuit-go-mod-cachefor reproducible buildsDocumentation
Detailed execution logs and checklists:
to_dict+ CGO)All executive summaries:
guides/optimizations/executive_summaries/