Precompute a per-column decode plan from COLMETADATA (row decode perf, axis: precomputation)

[saurabh500]

Sub-issue of #247 (axis: Precomputation).

Problem statement

For every column of every row, the decoder re-derives facts that cannot change within a result set:

• a ~40-arm match on data_type to pick the decode shape
• an is_plp() probe
• an encryption check (crypto_metadata.is_some())

Column metadata is fixed at COLMETADATA time. Over the PoC benchmark (1.5M rows × 48 columns) that is roughly 72M redundant classifications of constant metadata.

Proposed solution

Resolve each column once when COLMETADATA is parsed, into a dense plan, and dispatch on that in the row driver:

pub(crate) enum DecodeOp { Fixed(u8), ByteLen, ShortLen, LongLen, Plp, Fallback }
pub(crate) struct ColumnPlan { shape: DecodeOp, encrypted: bool }

Feasibility: ✅ proven for classification and wiring. Prototyped in b0e5132f (7 files, +211/−53), green on all six configs in #247.

Findings

• Where the plan lives matters a lot. Hanging it off ColumnMetadata looks cleanest but requires touching 54 struct literals repo-wide. Hanging it off ColMetadataToken as a OnceLock<Vec<ColumnPlan>> needs only 7, keeps #[derive(Default)] working so hand-built tokens in tests need just one extra field, and lets the parser fill it eagerly via OnceLock::from(...) so the hot path never touches lazy-init. Recommend the latter.

• The plan must reach the resumed row path too. RowPauseState has to carry a cloned copy alongside its existing columns clone, or a row that pauses mid-decode loses its plan.

• ⚠️ A subtle security-relevant bug the spike hit, and the fix. The first attempt folded encryption into the shape enum, returning Fallback for encrypted columns. That silently disabled the guard in drive_row_columns that refuses to stream ciphertext to PLP readers: an encrypted PLP column no longer compared equal to DecodeOp::Plp, so the stop_here && op == Plp check never fired and the UnimplementedFeature fail-fast was bypassed.

  io::token_stream::tests::ae_paused_plp_streaming_fails_fast caught it (passing count went 1696 → 1695).

  The rule this establishes: DecodeOp must describe the bytes on the wire only. Encryption is a separate bool on ColumnPlan. Any PR here needs an explicit test for encrypted-PLP classification.

  This also produced a faster path than the buggy version: decode_or_decrypt_column now early-returns on !plan.encrypted (one bool test) instead of probing an Option, and the residual match simplifies from match (meta.crypto_metadata.is_some(), decryptor) to match decryptor.

• plan(col) must re-derive on a short or absent plan, not default to Fallback. A wrong default silently changes decode behavior instead of merely costing time.

• Clippy pushed toward a better API. too_many_arguments fired at 8 params on drive_row_columns. Since columns, ops, and decryptor always travel together, they became one RowLayout<'a> borrow (Clone, Copy) — which also removes a class of bug where a caller could desynchronize them. drive_row_columns went 8 params → 6, pause_after_column 5 → 3.

• ⚠️ The spike stops at classification and wiring. The per-shape fast paths are still unwritten and are the bulk of the work. The real design challenge is doing that without creating a third copy of the type switch — decode, decode_into, and a plan-driven path. PR POC: reduce per-row cost in the TDS row decode path #238 does exactly this. Recommend the plan-driven path replace decode_into rather than sit beside it.

Affected crate

mssql-tds

Alternatives considered

Cache the classification on ColumnMetadata lazily per row. Still pays an Option probe per column and spreads mutable state into a type with 54 construction sites.

Build a closure/vtable per column. Reintroduces indirect calls, which is exactly what #251 and #252 are removing.

Additional context

token_stream.rs is the most contended file in the repo — it collides with the sans-I/O stack (#189–#203). Sequence this item accordingly.

Benchmark caveat: the PoC workload is 39 INT + 9 VARCHAR(6), which exercises 2 of 10 decode shapes. Benchmark against DATETIME2 / DECIMAL / UNIQUEIDENTIFIER before claiming this generalizes.

Implementation trivia from the spike: OnceLock<T> derives Clone/Debug/Default when T: Clone, which is required since ColMetadataToken derives all three. collect() into a OnceLock::from(...) argument needs an explicit Vec<ColumnPlan> annotation or you get E0283. The enum variant is TdsDataType::DateTim4, not DateTime4.

[saurabh500]

Benchmarked: currently a pure regression

Measured on the feasibility spike (b0e5132f) against the preceding commit, using the in-crate decode microbenchmark described in the results comment on #247.

Case	Before (ms)	After (ms)	Δ
39 INT + 9 VARCHAR(6)	61.0	63.7	+4.4%
same, every 4th column NULL	50.5	52.6	+4.1%
8 × VARCHAR(512)	26.0	26.5	+2.1%

This is exactly what the issue predicted: the plan is computed, cached on ColMetadataToken via OnceLock, and threaded through RowLayout — but no per-shape fast path consumes it yet. So the change currently adds a plan() lookup and an extra indirection per column and buys nothing back.

Note the benchmark is generous here: it builds ColMetadataToken by hand, and extract_row_context calls decode_plan(), whose OnceLock::get_or_init populates the plan once rather than re-deriving ColumnPlan::for_column per row. A naive implementation would look considerably worse.

Recommendation

Do not land this on its own. It should ship together with at least one consumer that demonstrates a win — otherwise it is a measured regression plus added surface area in the most contended file in the repo.

The classification work itself is sound and worth preserving, as is the Always Encrypted correctness fix it forced out (classifying encrypted columns as Fallback silently disabled the guard that refuses to stream ciphertext to PLP readers; caught by ae_paused_plp_streaming_fails_fast, and resolved by splitting ColumnPlan { shape, encrypted } so DecodeOp describes wire bytes only). That fix is independently valuable and could be separated out.

Caveat carried over from #247: this workload exercises 2 of 10 decode shapes. Re-benchmark against DATETIME2/DECIMAL/UNIQUEIDENTIFIER before concluding the plan generalizes — those are the shapes where a precomputed plan has the most re-derivation to save.

[saurabh500]

Porting findings here from #249, which duplicated this issue and is being closed. #249 was filed before I found this tree. This issue is the better base: it has a working spike and real measurements, which #249 did not.

Reconciling the two sets of numbers, because they disagree on the surface

#249 reported a resolved plan beating per-cell classification by -6.0% (39 IntN + 9 varchar), -3.3% (48 varchar), -13.8% (48 IntN). The spike here measured +4.4%. Both are correct; they measure different things.

• The Precompute a per-column decode plan (ColumnDecodeSpec) and converge all decode sites on it #249 harness is a standalone Criterion bench that models the decode loop with two hand-written arms. It measures the benefit of a resolved plan with none of the threading cost, and with per-shape fast paths assumed to already exist. It is an upper bound, not a prediction.
• The harness here drives the real receive_row_into_internal with the actual spike, where the plan is computed and threaded but nothing consumes it yet. That is the cost with zero benefit realized.

The gap between them is roughly the size of the per-shape fast paths that are still unwritten. Read -6% as the ceiling this work is chasing.

Warning

Read those #249 percentages in absolute terms. 48 varchar columns saved 291 us against 35 us for 48 IntN, an 8.3x gap, which is exactly what a per-cell classification chain predicts. intn48's -13.8% is the largest percentage but the smallest absolute saving; its baseline is 34x smaller. Quoted as a percentage it invites the opposite conclusion.

A fourth redundant per-cell derivation, beyond the three listed above

TimeN, DateTime2N and DateTimeOffsetN each call metadata.get_scale() and construct an ok_or_else closure per cell (decoder.rs:1290, :1309, :1330). Scale is fixed at COLMETADATA, so it belongs in the plan.

The string path's chain is also more specific than "a ~40-arm match + is_plp()". decode_string_into (decoder.rs:1716-1723) runs three classifications per cell before any I/O: get_encoding_type(metadata), metadata.is_plp(), and is_long_len_type(data_type). Worse than the instruction count: metadata is a &ColumnMetadata inside a Vec, so each one is a cold pointer chase into a fat struct.

Verified extent table

Read from the actual match arms rather than inferred, for filling out DecodeOp:

MS-TDS class	Types	Wire shape
FIXEDLEN	Int1(1) Int2(2) Int4(4) Int8(8) Flt4(4) Flt8(8) Bit(1) Money4(4) Money(8) DateTime(8) DateTim4(4)	value only, no prefix
BYTELEN	IntN FltN BitN MoneyN DecimalN NumericN DateTimeN DateN TimeN DateTime2N DateTimeOffsetN Guid	u8 length, 0 = NULL
USHORTLEN	BigBinary, non-PLP BigVarBinary, non-PLP BigChar/BigVarChar/NChar/NVarChar/Char/VarChar	u16 length, 0xFFFF = NULL
LONGLEN	Text, NText	u8 textptr length (0 means NULL), textptr, 8-byte timestamp, then u32 length
PARTLEN	anything where metadata.is_plp()	chunked

Warning

Guid (0x24) is BYTELEN, not FIXEDLEN. decoder.rs:1345 reads a length byte and then requires exactly 16. Easy to misfile as Fixed(16).

The residual _ => arm at decoder.rs:1364 falls back to self.decode(..) + write_column_value. Enumerating what actually lands there is what eventually lets Fallback be deleted rather than becoming a permanent escape hatch, which is the PoC's weakness.

On the shape of the plan entry: do not split extent from interpretation into two arrays

DecodeOp as defined here is extent-only, so the natural next step is adding the interpretation half. I benchmarked both shapes, one fused array versus two parallel arrays (a narrow extent array plus a wide interpretation array), expecting the split to win pass 1 on cache density:

Group	Schema	fused	split	Result
pass 1 only	39 IntN + 9 varchar	234.4 us	254.9 us	split 8.7% slower
	48 varchar	174.8 us	172.1 us	split 1.5% faster
	48 IntN	194.7 us	185.5 us	split 4.7% faster
two-pass total	39 IntN + 9 varchar	1.273 ms	1.280 ms	split 0.6% slower
	48 varchar	4.170 ms	4.251 ms	split 1.9% slower
	48 IntN	510.7 us	494.8 us	split 3.1% faster

Split lost 8.7% on the most realistic schema and was within +/-3% and directionally inconsistent everywhere else.

The density argument fails in principle, not merely in practice: a fused 48-column plan is 960 B, and SQL Server caps a result set at 1024 columns, so the worst case is 1024 x 20 B = 20 KB, still inside a 32 KB L1d. There is no reachable working set where the split's density can pay for itself.

So grow ColumnPlan with the interpretation field. Do not add a second array.

(20 B per entry because EncodingType::LcidBased(SqlCollation) is 16 B. I had estimated 4 B before measuring.)

Naming

#249 proposed ColumnDecodeSpec, on the grounds that plan: ColumnPolicy already appears at 10 sites in token_stream.rs (198, 223, 253, 269, 473, 584, 659, 766, 834), so ColumnPlan overloads "plan" in the exact functions that would carry one. To be accurate: that is a readability concern, not a compile blocker, and this spike is green using ColumnPlan. Worth a moment's thought, not worth a rename fight. plan: ColumnPolicy is arguably the mis-named one.

Harnesses

The two Criterion benches behind these numbers are on dev/saurabh/crispy-doodle (adc28f71). Caveat worth stating plainly: they model the decode loop rather than driving it, for exactly the reason given in the benchmark comment on #247, namely that receive_row_into_internal and friends are pub(crate) while a Criterion bench is a separate crate. The in-crate #[cfg(test)] approach used for this tree's measurements is the sounder one. decode_plan_shape.rs is still worth keeping for the fused-versus-split question, which the in-crate harness cannot easily answer.

[saurabh500]

Superseded by #249

Closing in favour of #249, which covers the same axis with a design that measurement says can actually pay for itself. This is a scope change, not a rejection — the spike findings recorded here are preserved in #249 as settled design constraints.

Why

The design prototyped here is:

pub(crate) enum DecodeOp { Fixed(u8), ByteLen, ShortLen, LongLen, Plp, Fallback }
pub(crate) struct ColumnPlan { shape: DecodeOp, encrypted: bool }

DecodeOp answers how many bytes a value occupies. It does not answer how to interpret them. So the ~40-arm match data_type still runs per cell, and the plan is consulted in addition to it rather than instead of it.

That makes the measured +4.4% a property of the design rather than an artifact of an unfinished implementation. The Fallback variant guarantees it: as long as the enum has an escape hatch, the old match must survive to service it, and the two can never collapse into one. No amount of downstream fast-path work removes that.

#249 instead specifies a fused ColumnDecodeSpec that carries interpretation and precomputed payloads (resolved encoding, width, precision/scale), covers every TdsDataType with no fallback variant, and requires the plan-driven path to replace decode_into rather than sit beside it. In an isolated harness that shape measures as a win on the same schemas (-6.0% on 39 IntN + 9 varchar, -3.3% on 48 varchar). The two results are not in tension — they measure two different designs.

Carried over to #249

• Where the plan lives: ColMetadataToken + OnceLock (7 touch points) over ColumnMetadata (54), filled eagerly by the parser so the hot path never hits lazy init.
• ⚠️ The Always Encrypted constraint, which is the most valuable thing this spike produced. Folding encryption into the shape enum silently disabled the guard in drive_row_columns that refuses to stream ciphertext to PLP readers, caught only by ae_paused_plp_streaming_fails_fast. Precompute a per-column decode plan (ColumnDecodeSpec) and converge all decode sites on it #249 records this as a hard rule: the spec describes wire bytes only, encryption rides alongside, and an explicit encrypted-PLP classification test is required.
• RowPauseState must carry a cloned plan.
• A short or absent plan must re-derive rather than default to a fallback variant, since a wrong default changes behaviour rather than merely costing time.
• The RowLayout<'a> borrow bundle, and the note that token_stream.rs is the most contended file in the repo.
• Implementation trivia: OnceLock<T> derive requirements, the E0283 annotation, TdsDataType::DateTim4.
• The 2-of-10 decode-shape benchmark caveat.

Also carried over

The recommendation from this issue that the plan-driven path should replace decode_into rather than sit beside it is now a stated requirement in #249, not just a recommendation — it is what prevents a third copy of the type switch.

The feasibility spike commit b0e5132f remains valid as a wiring reference for the OnceLock plumbing, even though its enum shape is not the one being pursued.