Skip to content

Commit 98119a5

Browse files
committed
docs: use the decimal scheme as the example of scheme variants
Drops the list of schemes with variants, which will change, and the frame-of-reference exception for child compression, which #10751 tracks as a bug. Signed-off-by: Connor Tsui <[email protected]>
1 parent a370079 commit 98119a5

1 file changed

Lines changed: 13 additions & 13 deletions

File tree

‎docs/specs/versioning/design.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -260,19 +260,19 @@ recording the minimum version.
260260

261261
The default BtrBlocks compressor uses only the schemes whose output it can write. A wire ID is
262262
allowed when the session registers it, the enabled editions permit it, and the compressor's preset
263-
does not exclude it. For example, the CUDA preset excludes the v2 IDs described below. The
264-
compressor excludes a scheme if any wire ID that the scheme declares is not allowed. Child arrays go
265-
through the same compressor, except that the frame-of-reference scheme always bit-packs its encoded
266-
child with the v1 bit-packing variant. The writer still checks every serialized ID, so a forbidden
267-
ID in any child fails the write.
268-
269-
The decimal, bit-packing, and frame-of-reference schemes each have a v1 and a v2 variant. The
270-
compressor uses the v2 variant when the v2 wire ID is allowed and the v1 variant otherwise, so
271-
callers do not choose the variant directly. The v2 variant also writes the v1 ID for arrays that fit
272-
the v1 format, so allowing only the v2 ID excludes the scheme. The v1 decimal variant constructs
273-
only single-child arrays, so values too wide for one 64-bit child remain in the standard
274-
uncompressed decimal representation. No declared edition permits a v2 ID yet, so a writer that
275-
enforces editions writes only v1 for these encodings.
263+
does not exclude it. For example, the CUDA preset excludes some v2 IDs. The compressor excludes a
264+
scheme if any wire ID that the scheme declares is not allowed. Child arrays go through the same
265+
compressor. The writer still checks every serialized ID, so a forbidden ID in any child fails the
266+
write.
267+
268+
A scheme can have variants that write different wire IDs. The compressor picks the variant from the
269+
allowed wire IDs, so callers do not choose it directly. For example, the decimal scheme uses its v2
270+
variant, which splits values too wide for one 64-bit child into several children, only when
271+
`vortex.decimal_byte_parts.v2` is allowed. Otherwise its v1 variant constructs only single-child
272+
arrays, and values too wide for one child remain in the standard uncompressed decimal
273+
representation. The v2 variant also writes the v1 ID for arrays that fit the v1 format, so allowing
274+
only the v2 ID excludes the scheme. No declared edition permits `vortex.decimal_byte_parts.v2` yet,
275+
so a writer that enforces editions writes only single-child decimal arrays.
276276

277277
[^decimal-availability]:
278278
No declared edition currently permits the multi-child format. The

0 commit comments

Comments
 (0)