PR #311 gave RowWriter a value-destination
sink so a consumer can have known-length PLP payloads written straight into its own storage.
That is a real win for varchar(max) / nvarchar(max) / varbinary(max), but it does nothing
for decimal / numeric, which never take the PLP path.
In the PostgreSQL FDW workload that motivated #311, numeric is the one column class where the
#299/#311 stack still loses badly to the poc/tds-decode-fdw-usage branch:
| workload | poc/tds-decode-fdw-usage |
PR #311 |
|---|---|---|
| fixed | 725.9 ms | 662.1 ms |
| text | 1410.1 ms | 1282.6 ms |
| binary | 1080.9 ms | 801.3 ms |
| numeric | 1510.7 ms | 2673.2 ms |
mixed (SELECT *) |
3952.6 ms | 4032.7 ms |
1,000,049 rows, 4 numeric columns, medians of a 12-round balanced interleave.
The gap is not a TDS-protocol problem. It is two things: the decoder allocates twice per numeric
value, and the only way to get a value out is a freshly allocated String. This note proposes
six changes, five of which are backwards compatible, and measures each one.
Everything below is reproducible: numeric_decode.rs reproduces the three decode shapes and
five format shapes byte for byte, asserts they all agree, and only then times them.
microsoft/mssql-rs#313 implements R1 + R2 + R5 as layer 6 of stack #287, on top of #311. Measured in-repo, ns/value:
| workload | before | after | speedup |
|---|---|---|---|
| decode, FDW columns | 34.75 | 4.19 | 8.3x |
decode, decimal(38,10) |
40.09 | 4.18 | 9.6x |
format, FDW columns (format_into) |
83.15 | 17.05 | 4.9x |
format, decimal(38,10) (format_into) |
155.89 | 88.33 | 1.8x |
Decode landed ~3x better than the ~13 ns this note projected.
Two corrections that implementation forced, both folded into the text below:
- The two-limb split formatter in R5 was wrong — it silently truncated above
u64::MAX × 10¹⁹. Three limbs are required. See R5. - R1's
pub magnitude: u128field is the wrong representation — au128field imposes 16-byte alignment, which propagates into the row-fetch async state machines and grows them past their size budget. Store[u64; 2]privately behind an accessor. See R1.
R4 is subsumed by R1 and is no longer a separate recommendation: once DecimalParts is Copy
and carries the magnitude inline, a typed writer entry point is a pure API addition with no
representation work behind it. R3 overlaps #303–#307. R6 remains open and is the largest
outstanding win.
| # | Change | Breaking? | Measured effect |
|---|---|---|---|
| R1 | Carry the magnitude inline in DecimalParts (u128), make it Copy |
yes | enables R2 |
| R2 | Decode into a [u8; 16] + u128::from_le_bytes; drop both heap allocations |
no¹ | 2.6x faster decode (3.9x on decimal(38,10)) |
| R3 | Sync-first read for the magnitude bytes | no | removes one .await per value |
| R4 | write_decimal_compact default method taking a Copy decimal |
no | subsumed by R1 — see Status |
| R5 | format_into(&mut [u8; 48]) -> &str instead of to_decimal_string() -> String |
no | 5.6x faster formatting (1.6x on decimal(38,10)) |
| R6 | Optional base-10000 digit export | no | 10.4x vs today, and removes the consumer's text parse |
¹ R2 is internal. It is fully realised only with R1, but it can be applied on its own — see "If you cannot break the API".
End to end, per decoded value, for the FDW's four numeric columns:
| path | ns / value | vs #311 |
|---|---|---|
#311 head: decode + to_decimal_string |
124.6 | 1.00x |
POC branch: decode + to_decimal_string |
107.6 | 1.16x |
proposed: decode + format_into |
23.7 | 5.25x |
| proposed: decode + base-10000 digits | 11.5 | 10.84x |
All line references are against 890ef66 (head of PR #311).
GenericDecoder::read_decimal_data — mssql-tds/src/datatypes/decoder.rs:742-790:
validate_alloc_size(number_of_int_parts * 4, "read_decimal int_parts")?;
let mut magnitude = vec![0u8; number_of_int_parts * 4]; // alloc #1, zeroed
reader.read_bytes(&mut magnitude[..magnitude_len]).await?; // copy #1
let int_parts = magnitude
.chunks_exact(4)
.map(|chunk| {
let mut word = [0u8; 4];
word.copy_from_slice(chunk);
i32::from_le_bytes(word)
})
.collect(); // alloc #2, copy #2
Ok(Some(DecimalParts { is_positive, scale, precision, int_parts }))The payload here is at most 16 bytes. MAX_DECIMAL_INT_PARTS is 4 (decoder.rs:158), and it
is checked immediately above. So the code pays a malloc, a memset, a second malloc, two copies,
and later two frees, to move up to sixteen bytes that are already sitting in the packet buffer.
DecimalParts itself (decoder.rs:2062-2071) is what forces this:
pub struct DecimalParts {
pub is_positive: bool,
pub scale: u8,
pub precision: u8,
pub int_parts: Vec<i32>, // <- the whole problem
}The POC branch's sync row path (io/token_stream.rs:569-590) halves this — it drops the staging
buffer and pushes straight from the borrowed packet buffer — but it still does
Vec::with_capacity((length - 1) / 4), so one malloc/free per numeric value survives on every
branch measured so far, including the POC.
Note also that 890ef66 has no DecodeOp and no sync row path, so at #311 the async
read_decimal_data above is the only decimal path.
number_of_int_parts <= MAX_DECIMAL_INT_PARTS is checked on the line above, so the size argument
is <= 16 by construction. The call is a branch and a function call per value that can never fire.
The length and sign bytes use read_sync_first!, but the magnitude does not — it goes through
reader.read_bytes(..).await. TdsPacketReader has try_read_byte / try_read_uint32 /
try_read_int64 and so on (io/packet_reader.rs:15-69) but no try_read for a byte run.
to_decimal_string — decoder.rs:2222-2247:
let value_str = magnitude.to_string(); // alloc
let result = format!("{}.{}", &value_str[..split_pos], &value_str[split_pos..]); // alloc + copy
if self.is_positive { result } else { format!("-{}", result) } // alloc + copyThis is the only way to get full precision out of DecimalParts. to_f64 loses precision;
magnitude() is public but returns the unscaled integer, so a caller still has to place the
decimal point itself. Every text-input consumer — PostgreSQL numeric_in, ODBC SQL_C_CHAR,
Python Decimal(str), JSON serialisation — lands here.
At 81 ns/value it is the single most expensive thing in the numeric path, more than twice the cost of the decode it follows.
A valid decimal/numeric has precision ≤ 38, so the magnitude is < 10³⁸ < 2¹²⁷ and always
fits in a u128. The existing MAX_DECIMAL_INT_PARTS = 4 already encodes exactly this.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DecimalParts {
pub is_positive: bool,
pub scale: u8,
pub precision: u8,
magnitude: u128,
}magnitude() (decoder.rs:2267) becomes a field read instead of a rposition scan plus a fold.
magnitude_big() (decoder.rs:2288) and its BigUint allocation become dead for anything the
decoder produces — read_decimal_data already rejects more than four words, so the None arm
of magnitude() is unreachable on the decode path today. Keep BigDecimal for from_string,
which is the encode/bulk-copy direction and genuinely needs it.
Store [u64; 2], not u128. The sketch above reads well but costs more than it looks. A
u128 field gives DecimalParts 16-byte alignment, which propagates through ColumnValues into
the generated row-fetch async state machines; in #313 that grew next_row_cursor from 4248 to
4400 bytes and tripped the crate's future-size guard. Keeping the storage private and 8-aligned
avoids the whole problem, and one shift-plus-or on read is free relative to the decode it replaces:
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DecimalParts {
pub is_positive: bool,
pub scale: u8,
pub precision: u8,
/// Little-endian halves. Deliberately not `u128`: that would force
/// 16-byte alignment on every type that embeds this one.
magnitude: [u64; 2],
}
impl DecimalParts {
#[inline]
pub fn magnitude(&self) -> u128 {
(self.magnitude[1] as u128) << 64 | self.magnitude[0] as u128
}
}That lands DecimalParts at 24 bytes, align 8 — 8 bytes smaller than the Vec-based struct
it replaces — and leaves the row-fetch futures byte-for-byte unchanged. Expose word(i) /
word_count() / from_words(..) alongside it for the wire encoders and the JS FFI, which want the
little-endian 32-bit view.
This is the one breaking change, because int_parts is a public field. Options:
-
Preferred while the crate is
0.1.0: change it, and keep apub fn int_parts(&self) -> ArrayVec<i32, 4>(or([i32; 4], usize)) accessor for anyone who was reading the words. -
Compatible: leave
DecimalPartsalone, add a newCompactDecimaland route the fast path through R4. See "If you cannot break the API". -
Preferred while the crate is
0.1.0: change it, and keep apub fn int_parts(&self) -> ArrayVec<i32, 4>(or([i32; 4], usize)) accessor for anyone who was reading the words. -
Compatible: leave
DecimalPartsalone, add a newCompactDecimaland route the fast path through R4. See "If you cannot break the API".
let length = read_sync_first!(reader, try_read_byte, read_byte);
if length == 0 { return Ok(None); }
let is_positive = read_sync_first!(reader, try_read_byte, read_byte) == 1;
let mut word = [0u8; 16];
reader.read_bytes(&mut word[..(length - 1) as usize]).await?;
Ok(Some(DecimalParts {
is_positive,
scale,
precision,
magnitude: u128::from_le_bytes(word),
}))Because TDS is little-endian and the array is zero-initialised, u128::from_le_bytes is the
reassembly. The chunks_exact / map / collect disappears. The zero-initialised array also
preserves the existing zero-padding semantics for a short read for free, which is what the
comment at decoder.rs:758-761 is protecting — so div_ceil can stay if the second call site
needs it (see "What this does not address").
validate_alloc_size goes away with the allocation.
Measured, 16,384 values of decimal(15,2), decimal(15,2), decimal(18,3), decimal(19,4):
| decode shape | ns / value | speedup |
|---|---|---|
#311 head (vec! + chunks_exact.collect) |
34.6 | 1.00x |
POC sync row (Vec::with_capacity + push) |
24.8 | 1.40x |
proposed ([u8; 16] + from_le_bytes) |
13.3 | 2.61x |
On decimal(38,10) (17-byte wire, four words) the gap widens, because the per-word loop is
longer and the allocation is bigger:
| decode shape | ns / value | speedup |
|---|---|---|
| #311 head | 39.9 | 1.00x |
| POC sync row | 24.8 | 1.61x |
| proposed | 10.2 | 3.89x |
The proposed decode gets faster on wide values than narrow ones (10.2 vs 13.3 ns), because the work is now a fixed-size 16-byte copy regardless of precision.
read_sync_first! already exists and is used for the length and sign. Add the missing primitive
so the magnitude can use it too:
fn try_read_bytes(&mut self, buf: &mut [u8]) -> bool { .. }
// or, better for this call site:
fn try_read_array<const N: usize>(&mut self) -> Option<[u8; N]> { .. }A borrowed variant — try_read_slice(len) -> Option<&[u8]> — would also let the sign and
magnitude be taken in one borrow, which is the same trick the POC branch's sync row path uses
and the same spirit as #311's borrowed destinations.
Without any new primitive there is still a cheap win available: decimal(p ≤ 9) is one
try_read_uint32 and decimal(p ≤ 19) is one try_read_int64, both of which already exist.
That covers essentially every real schema.
(Not separately quantified here — this micro-benchmark reads from an in-memory buffer, so it
cannot show the .await cost. It is included because it is the same class of change and free
to make alongside R2.)
Subsumed by R1. Once
DecimalPartsis itselfCopyand carries the magnitude inline — as shipped in #313 — this becomes a pure API addition with no representation work behind it, and there is no longer a reason to introduce a separateCompactDecimal. The section is kept because it remains the right answer under "If you cannot break the API", whereDecimalPartsmust stay as it is.
#311 added opt-in RowWriter methods with defaults so no existing consumer breaks. Do the same
for decimals:
/// A decoded `decimal`/`numeric`. Never allocates.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct CompactDecimal {
pub is_positive: bool,
pub precision: u8,
pub scale: u8,
pub magnitude: u128,
}
pub trait RowWriter {
// ...
/// Receives a decimal without allocating. The default forwards to
/// [`RowWriter::write_decimal`], so existing implementations are unaffected.
fn write_decimal_compact(&mut self, col: usize, val: CompactDecimal) {
self.write_decimal(col, val.into());
}
fn write_numeric_compact(&mut self, col: usize, val: CompactDecimal) {
self.write_numeric(col, val.into());
}
}Consumers that override pay zero allocations. Consumers that do not pay exactly what they pay
today, because the From<CompactDecimal> for DecimalParts conversion rebuilds the Vec. This is
precisely the #311 contract — opt in for the fast path, default for compatibility — and it means
R4 can ship without R1.
Replace the to_string() + format! splice with a single reverse pass into a caller-supplied
buffer. 38 digits + sign + point + slack fits in 48 bytes:
impl DecimalParts {
/// Renders the value into `buf` and returns the populated prefix.
/// Never allocates.
pub fn format_into<'a>(&self, buf: &'a mut [u8; 48]) -> &'a str { .. }
}
// keep the old entry point as a thin wrapper
pub fn to_decimal_string(&self) -> String {
self.format_into(&mut [0u8; 48]).to_owned()
}One caveat worth stating, because I got it wrong first. The obvious implementation —
buf[pos] = b'0' + (mag % 10) as u8; mag /= 10; on the u128 — is slower than to_string()
on wide values, because every u128 / 10 is a __udivti3 libcall while u128::to_string() uses
a chunked algorithm.
The fix is one u128 division per limb. Split by 10¹⁹ into u64 limbs and generate every digit
with u64 arithmetic, which the compiler turns into a multiply-shift.
Use three limbs, not two. An earlier revision of this gist showed a two-limb split, and it was wrong:
// WRONG — silently truncates
let (hi, lo) = ((magnitude / P19) as u64, (magnitude % P19) as u64);magnitude / 10¹⁹ exceeds u64::MAX as soon as magnitude > u64::MAX × 10¹⁹ ≈ 1.845e38, and the
as u64 cast then discards the overflow with no diagnostic. A u128 reaches 39 digits and
u128::MAX ≈ 3.403e38, so the top of the range is unrepresentable: u128::MAX rendered as
155814926183842947303374607431768211455 instead of 340282366920938463463374607431768211455.
A legal decimal(38, s) tops out at 10³⁸ − 1 ≈ 9.99e37 and never reaches the cutoff, so this is
unreachable through a conforming wire value — but DecimalParts accepts an arbitrary u128, and
16 bytes of 0xFF off the wire will reach it. Three limbs cover the full domain:
const P19: u128 = 10_000_000_000_000_000_000;
let mut lo = (magnitude % P19) as u64; // digits 0..18
let mut mid = ((magnitude / P19) % P19) as u64; // digits 19..37
let mut hi = (magnitude / (P19 * P19)) as u64; // digits 38+
// emit 19 digits from `lo`, then 19 from `mid`, then the rest from `hi`,
// inserting '.' after `scale` digits. The limbs are positional, so a limb
// that empties early still yields zeros until its 19 slots are spent.Credit for catching this: it surfaced during the implementation of R1/R2/R5 in
microsoft/mssql-rs#313, and only because the
implementer's oracle was the independent u128::to_string() + splice rather than a reuse of the
same limb decomposition. An oracle that shares arithmetic with the kernel it validates would have
been wrong in exactly the same way and the corpus would have passed. benches/numeric_decode.rs
now carries a check_adversarial() corpus — u128::MAX, every 10ᵏ and 10ᵏ−1 for k ≤ 38, the exact
two-limb cutoff and its neighbours, and 20 000 deterministic random magnitudes across 9 scales and
both signs, 361 656 cases — which fails against the two-limb version and passes against this one.
The original workload-shaped corpus could not have caught it, because every magnitude it generates
is a legal decimal(38, s).
Measured, the FDW's four columns:
| formatter | ns / value | vs today |
|---|---|---|
to_decimal_string (today) |
81.4 | 1.00x |
| naive reverse loop | 21.1 | 3.87x |
u64-only fast path (p ≤ 19) |
12.0 | 6.79x |
| split-by-10¹⁹ (handles all widths) | 14.6 | 5.59x |
and on decimal(38,10) with a magnitude just under 10³⁸:
| formatter | ns / value | vs today |
|---|---|---|
to_decimal_string (today) |
159.3 | 1.00x |
| naive reverse loop | 219.5 | 0.73x — slower |
u64-only fast path |
222.1 | 0.72x — slower |
| split-by-10¹⁹ | 97.8 | 1.63x |
The third limb costs nothing measurable: it is one extra u128 division at setup, and the digit
loop's limb selection is a comparison against a counter that was already being maintained.
Ship the split version as the single implementation: it is 5.6x on narrow values and still 1.6x
on the widest ones. The u64-only variant is quicker on narrow input but degenerates to the
naive loop above 19 digits, so it is not worth the branch.
Buffer bound. 48 bytes is exactly tight, not generous: the worst case is a negative u128::MAX
at scale = 45, which writes 46 digits + '.' + '-' = 48. Within the legal scale ≤ 38 domain
the worst case is 41. If you take a scale from the wire without validating it, bound it before
formatting.
Any consumer that stores decimals in a base-10⁴ representation — PostgreSQL's numeric is
exactly this: int16 digits, a weight, a sign and a display scale — currently has to go
u128 → decimal string → parser → base-10⁴. Both ends of that round trip are pure overhead.
impl DecimalParts {
/// Base-10000 digits, most significant first. Returns `(ndigits, weight)`.
pub fn to_base10000(&self, out: &mut [i16; 12]) -> (usize, i32) { .. }
}| export | ns / value (FDW cols) | ns / value (38,10) |
|---|---|---|
to_decimal_string (today) |
81.4 | 159.3 |
to_base10000 |
7.8 | 106.9 |
That is 10.4x on the FDW columns, and it deletes the consumer's numeric_in parse on top,
which this benchmark does not even count. On a full 38-digit value the margin narrows to 1.5x,
because carry propagation across eleven base-10⁴ digits is real work.
⚠️ Implementation trap — do not pre-scale the magnitude.To align the fractional part onto a base-10⁴ boundary you need to multiply by
10^padwherepad = (4 - scale % 4) % 4. The obvious place to do it is on theu128before converting:let mut mag = self.magnitude * 10u128.pow(pad as u32); // WRONGFor
decimal(38, s)withs % 4 != 0, the magnitude reaches 10³⁸ − 1 and10³⁸ × 100 ≈ 10⁴⁰does not fit in au128(max ≈ 3.40 × 10³⁸). In a release build this wraps silently and yields a completely wrong number:magnitude : 99999999999999999999999999999999999998 magnitude * 100 : 131811359292784559562136384478721867576 <- wrapped checked_mul : NoneConvert to base-10⁴ first, then scale the digit array with carry propagation. The largest intermediate is then
9999 * 1000 + carry, which fits in au32. The FDW POC'snumeric_binary_inputgets this right; my first draft of this gist did not.
This one is arguably out of scope for a TDS crate, since base-10⁴ is a PostgreSQL detail.
If so, R1/R4 alone are enough — once the magnitude is reachable as a u128, a consumer can
do this conversion itself in ~8 ns. The important thing is that today it cannot, because the
only lossless accessor returns a String.
Decode plus "make it usable", per value, over the FDW's four numeric columns:
| path | ns / value | vs #311 head |
|---|---|---|
#311 head: read_decimal_data + to_decimal_string |
124.6 | 1.00x |
POC branch: sync-row decode + to_decimal_string |
107.6 | 1.16x |
R2 + R5: inline decode + format_into |
23.7 | 5.25x |
| R2 + R6: inline decode + base-10000 | 11.5 | 10.84x |
Note how little the POC branch's decode work buys once formatting is included — 1.16x. The POC's
real numeric win in the FDW came from the consumer using PostgreSQL's binary numeric receive
instead of numeric_in, i.e. it routed around to_decimal_string rather than making it cheaper.
R5 and R6 make that win available to every consumer instead of only to one that can bypass the
crate.
What this is worth in the FDW measurement. The numeric workload is 1,000,049 rows × 4 columns = 4,000,196 values, and measured 2673 ms at #311. Straight arithmetic on the per-value figures above:
- in-process decode + format at #311: ~498 ms of that 2673 ms
- with R2 + R5: ~95 ms, so ~403 ms saved, roughly 15%
- with R2 + R6: ~46 ms, ~452 ms saved, plus the
numeric_inparse that disappears with it
This is extrapolation from a micro-benchmark, not an end-to-end measurement — the rest of the 2673 ms is network, tuple forming and executor overhead that none of this touches. Treat ~15% as the honest floor for the text path and rather more for the binary one.
It is also not enough to beat the POC on its own. The POC's numeric advantage is ~1162 ms,
and only about a third of that is reachable from inside mssql-tds. The rest is PostgreSQL's
numeric_in on the consumer side, which R5 cannot touch — you need R6 and a consumer that
switches to binary receive. R5 is still the change worth shipping, because it benefits every
text consumer of the crate; it just is not the whole story for this particular FDW.
R1 is the only breaking change. Without it you still get most of the benefit:
- R5 (
format_into) is purely additive and is the largest single win — 5.6x on formatting. - R6 (
to_base10000) is purely additive. - R4 (
write_decimal_compactwith a defaulted forward) is purely additive, and lets the decoder run R2's allocation-free path internally, materialising aDecimalPartsonly for consumers that did not opt in. - R2 can be applied halfway on its own: read into
[u8; 16]on the stack, then build theVec<i32>from it. That kills one of the two allocations and the memset without touching any public type.
The combination R2(partial) + R4 + R5 is backwards compatible and captures most of the 5.25x.
The POC branch's DecodeOp plan — resolving each column's type, precision and scale once per
result set rather than re-matching metadata.type_info.type_info_variant on every value — is
orthogonal to everything above and applies to every type, not just decimals. At #311 head,
read_decimal (decoder.rs:721-740) re-destructures the metadata enum per value. That is
already prototyped on 9df51f0; it should not be left on a POC branch.
Gists are flat, so recreate the two-file layout:
mkdir -p tds-numeric-bench/benches && cd tds-numeric-bench
# Cargo.toml at the root, numeric_decode.rs into benches/
cargo benchnumeric_decode.rs asserts that all three decode shapes and all five format shapes produce
identical results before it times any of them, on both workloads, so the numbers are comparable
by construction. The base-10⁴ encoding is validated by rendering it back to a decimal string
rather than by reconstructing the magnitude — reconstruction would hit the very u128 overflow
the encoder exists to avoid, so it cannot serve as its own oracle.
The workload mirrors the FDW regression table:
CAST((n % 10000000) * 0.01 AS decimal(15,2)) AS n1,
CAST((n % 1000000) * -0.01 AS decimal(15,2)) AS n2, -- negative: exercises the extra format!
CAST((n % 100000) * 0.001 AS decimal(18,3)) AS n3,
CAST((n % 10000) * 0.0001 AS decimal(19,4)) AS n4plus a decimal(38,10) workload whose magnitude sits just under 10³⁸ — the true maximum for
precision 38 — to exercise the four-word path and the overflow trap described under R6.
Environment for the numbers above: AMD EPYC 7763, Ubuntu 24.04 (WSL2, kernel 6.6.87.2),
rustc 1.93.1, opt-level=3, lto="fat", codegen-units=1. Criterion medians; run-to-run
variation was under 2%. Raw output in results-linux.txt.
- NULL handling and the
length == 0path — unchanged, already cheap. - The
sql_variantcaller —read_decimal_datahas a second call site atdecoder.rs:2356, where the length comes from the variant header rather than from aDecimalNfield. If that path can present lengths outside{5,9,13,17}, keep the length-tolerantdiv_ceilwidth calculation there. The[u8; 16]rewrite is compatible either way: the array is zero-initialised, so a short read leaves the high bytes zero exactly as the stagingVecdid. money/smallmoney— separate types with their own decode, not touched here.from_string/ bulk copy — the encode direction still wantsBigDecimal. None of the above changes it.