Skip to content

feat: add exact decoded length and validation APIs - #22

Open
patrickZWY wants to merge 4 commits into
fast:mainfrom
patrickZWY:feat/decode-inspection
Open

patrickZWY wants to merge 4 commits into
fast:mainfrom
patrickZWY:feat/decode-inspection

Conversation

@patrickZWY

@patrickZWY patrickZWY commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add two allocation-free methods to Codec and concrete Base16, Base32 and Base64 profiles:

  • decoded_len computes the exact output size if decoding succeeds.
  • check validates encoded input without producing decoded bytes, preserving DecodeError precedence and byte offsets.

Closes #12.

Design Notes

  • Reuse decode planning for sizing; decoded_len checks length and trailing padding shape without full validation.
  • Share decoding tables, SIMD classification predicates and tail-bit rules. Backend selection remains private.
  • Eight-vector AVX2 batches balance bulk throughput and first-error recovery cost; larger batches win some cases.
Shared decode plan
+-- decoded_len --> Exact size if decoding succeeds
+-- check
    +-- Base16 --> Scalar checks --> Result
    +-- Base32 --> Scalar checks --> Unused-bit checks --> Result
    +-- Base64
        +-- Prefix < 16 B --> Scalar checks
        +-- Prefix >= 16 B --> First-symbol check --> Select backend
            +-- Scalar fallback / Miri
            +-- SSSE3 --> 16-byte loop
            +-- AVX2
                +-- 16-31 B --> 16-byte kernel
                +-- 32-255 B --> 32-byte loop + bounded tail
                +-- 256 B or more --> Bulk path
                    +-- Check first 64 B and align
                    +-- Check 8 x 32-byte batches
                    +-- Rescan a failing batch for the first error
                    +-- Finish with bounded block/tail checks

Base64 completion: remaining symbols --> unused-bit checks --> Result.

Thresholds use encoded complete-prefix bytes. Scalar checks use short loops or eight-byte lookup batches. All paths preserve decoding error precedence and original byte offsets. SIMD reads are bounded; no decoded output is allocated or written.

Performance Evidence

Compared scalar/SIMD paths, 2/4/8/16-vector batches, thresholds, alignment and tails. macOS sampling and disassembly guided classification and batching changes. Experimental tools remain outside this PR.

Method: rustc 1.100.0 / LLVM 23.1.5, thin LTO, one codegen unit; matched inputs, lockfile, rounds and executable paths. Six order-balanced samples per candidate; five interleaved peer samples. No allocation in repeated loops. Tables report median batch milliseconds; lower is better within each row. Initial SIMD is an earlier validation prototype, not main. Candidates include their dispatch and error-recovery paths.

Environment: Mac i5-8279U, no affinity; Ubuntu i5-1230U, pinned P-core 0/E-core 4, powersave governor, no fixed frequency or SMT isolation.

CPU Workload Initial SIMD Selected, 8 vectors 16-vector candidate
Mac Mixed valid 630.5 433 423
P-core Mixed valid 366 269 274
E-core Mixed valid 881 704.5 695.5
Mac 1 MiB, aligned 299.5 195.5 181
Mac 1 KiB, invalid at offset 64 293.5 374 549
P-core 1 KiB, invalid at offset 64 214.5 254 301
E-core 1 KiB, invalid at offset 64 300 437 683.5

Interpretation (lowest observed medians): The 16-vector candidate wins the Mac/E-core mixed-valid rows and the Mac 1 MiB row. Eight vectors win the P-core mixed-valid row; initial SIMD wins all three offset-64 rejection rows. We choose eight vectors for the throughput/recovery trade-off: mixed-valid time is 20-31% below initial SIMD, while rejection time is 16-36% below the 16-vector candidate in the displayed cases.

Mixed pool: 200 messages, 60% 8 B / 20% 32 B / 10% 1 KiB / 10% 16 KiB. Sizes are raw bytes; offsets are encoded bytes. Current ecosystem comparison (base64-simd 0.8.0):

CPU, 16 KiB valid Bases check Bases decode base64-simd check
P-core 171 423 181
E-core 470 1247 424

Interpretation (lowest observed medians): Bases check wins on the P-core, using 5.5% less time than base64-simd. base64-simd wins on the E-core, using 9.8% less time than Bases check. Bases check uses 60-62% less time than full Bases decoding on both cores. The validators have different error-reporting contracts, as noted below.

Decoder integration follow-up (benchmark-only)

Compared the existing SIMD decoder at this PR's a71dae2 with three isolated prototypes: validate first then decode without repeating SIMD validation, or fuse error checks across four/eight vectors. The classifier is already shared in the PR baseline; this measures additional batching, not an upgrade from scalar decoding. No experimental implementation, harness or result files are included in this PR.

Screened 39 deterministic scenarios with eight order-balanced samples per version on Mac and each Ubuntu core, including buffer/owned/uninitialized/in-place output, URL profiles, alignment, rejection and mixed messages. Source, harness, lockfile, compiler and release settings matched across variants; native binary hashes were verified. Fixture setup and reusable-buffer allocation were excluded; owned allocation/drop and in-place input restoration were included. Builds/tests/disassembly finished before timing; Ubuntu cores ran sequentially.

P-core variability prompted separate confirmation of nine scenarios: baseline versus each fused decoder, 16 alternating ABBA/BAAB blocks per pair/core, 32 samples per version/pair, approximately 50 ms baseline samples and equal fixed rounds. The table reports the median of within-block candidate/baseline mean-time ratios as elapsed-time changes; negative is faster. All samples/outliers were retained, with screening and confirmation analyzed separately.

CPU Valid raw input 4-vector decoder 8-vector decoder
P-core 1 KiB -11.0% -8.3%
P-core 16 KiB -5.3% -5.0%
P-core 1 MiB -4.9% +0.4%
E-core 1 KiB +0.8% +6.4%
E-core 16 KiB -0.3% +7.8%
E-core 1 MiB +2.4% +11.5%

For a 1 KiB message with ! at encoded offset 256, rejection took 2.88x/2.20x the baseline with four vectors and 6.01x/4.20x with eight (P-core/E-core); every confirmation block was slower. The fused prototypes recover the first error by scalar-scanning the failed batch, so this does not establish a lower bound for SIMD error recovery. The separate validate-then-decode prototype also showed no consistent cross-platform advantage; initial 1 MiB elapsed times increased 22.8% on Mac and about 11% on both Ubuntu cores.

The results support keeping batching specific to the validation workload in this PR. Full decoding still performs value conversion, bit packing and output stores; eight-vector fusion also introduced vector stack accesses in both platforms' assembly. These are code/disassembly observations, not hardware-counter attribution. The earlier check versus decode table compares different work and cannot be used as a decomposition of decoder cost. Further SIMD error-recovery improvements remain unmeasured.

Validation

  • cargo x test (715 executions), cargo x check, cargo x lint and 209 retained benchmark output checks pass.
  • Independent contracts cover exact capacity, optional padding and errors; kernel tests cover alphabets, byte values, alignment, boundaries and first-error recovery.
  • Rust 1.88/static AVX2/SSSE3 compile checks and native Ubuntu tests passed.
  • Each of the three experimental decoder candidates passed cargo x test (715 executions per candidate/platform) on Mac and Ubuntu, all 209 existing benchmark output checks, and additional independent-alphabet/wire-byte, first-error, batch-boundary, in-place/uninitialized-output and buffer-canary checks. These prototype checks are separate from validation of the committed PR code.

Formal verification

  • External Verus (--no-cheating, a71dae2) verifies sizing/overflow, Base16/32/64 structural plan acceptance, scalar/tail initialization, Base64 packing, and explicit SIMD bounds/alignment, append/in-place/streaming models. Latest evidence adds Base32 tail bytes/error precedence, an ASCII word projection, and initialization-to-array/append adapters (20 checks, 0 errors).
  • Deterministic oracle/source tests, ASan, and focused Miri pass. Unsupported iterator/raw-slice/Vec operations remain explicit boundaries; actual SIMD semantics, raw-pointer permissions, and complete production publication/streaming correctness remain unproved. Evidence and tooling stay outside this PR.

Considerations

  • Longer-batch retests confirm offset-64 rejection costs 2–7 ns/call more than initial SIMD. At 24 B, median time increases 1–4%; the earlier 12 B slowdown was not reproduced.
  • base64-simd wins on the tested E-core and some short workloads; its errors omit byte offsets.
  • A separate retest against main at 94be0ba used the repository harness and 16 samples/version in ABBA/BAAB blocks. Small decoder regressions include Mac Base32/8 B and Base64/8 B median increases of 2.3% and 0.7%; results vary with build/test context.
  • Synthetic traces on two Intel machines do not establish AMD, ARM, SSSE3-only or production performance. Frequency, scheduling and code layout can affect results.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Evaluate exact decoded_len and validation-only check APIs

1 participant