Module blob 

The tensor blob: a size-prefixed, append-only serialization of a tensor.

Why a blob and not the descriptor

TensorDesc is a fixed C struct with one handle and no plane table. The blob carries every plane explicitly, in either of two transport modes, and survives being appended to.

Layout

Region order is permanent from first publication. The format is size-prefixed and append-only: a new field may only be appended, never inserted, and required_mask covers the one case appending cannot — an addition that changes how existing fields are interpreted, where an unaware consumer must refuse rather than proceed.

The fixed header is 64 bytes, laid out widest-first so every scalar is naturally aligned and no reader performs an unaligned access:

Offset	Type	Field
0	u64	size — total blob bytes
8	u64	required_mask
16	u64	planes_bytes
24	u32	storage_kind
28	u32	pid
32	i32	fence_fd
36	u32	dtype
40	i32	quant_axis
44	u32	ndim
48	u32	plane_count
52	u32	quant_scales_len
56	u32	quant_zero_points_len
60	u32	strings_bytes
64	u32	strides_len — ndim entries, or 0 for densely packed
68	u32	reserved, must be zero — keeps the tail 8-aligned

strides_len is carried rather than assumed because empty strides are a distinct, meaningful value: Tensor.msg defines an empty array as “densely packed C-order”. Always writing ndim strides would be simpler but would turn a message with empty strides into a blob with explicit ones, so the reference-mode round-trip would no longer be the identity.

Because every variable region’s length lives in the fixed header, each region’s offset is a constant-time arithmetic derivation. This is the one thing CDR cannot do — it has no offset table, so a message’s variable fields must be walked sequentially — and it is why the blob is worth having alongside the message rather than simply reusing it.

Every integer is little-endian on every host, read and written explicitly. The blob is never transmuted from a struct: that would bake in host byte order and padding, and this format crosses hosts.

Structs

BlobHeader

The blob’s fixed header. See the module docs for the byte layout.

BlobPlane

One plane record, borrowed from the buffer.

BlobStrings

The blob’s five strings, borrowed from the buffer.

BlobView

A parsed, validated view over a blob.

Regions

Byte offsets of every variable region, derived from the fixed header.

Enums

BlobError

What went wrong parsing a blob.

TransportMode

How a plane’s bytes cross a boundary.

Constants

D3D11_HANDLE_BYTES

Bytes a Windows D3D11 reference plane carries in BlobPlane::handle_bytes: three little-endian u64s, in order the texture NT handle value, the fence NT handle value and the fence value of the last recorded GPU write.

HEADER_LEN

Bytes in the fixed header. See the module docs for the field table.

HEADER_PID_OFFSET

Byte offset of BlobHeader::pid inside the fixed header, as the table in the module docs assigns it. Named so nothing re-derives the layout by hand; pid_offset_matches_the_writer pins it to what BlobHeader::write_to actually emits.

PLANE_RECORD_LEN

Bytes in a plane record’s scalar block, before its variable payloads.

SUPPORTED_REQUIRED_MASK

required_mask bits this build understands. Zero: no interpretation-changing field has been added yet, so any bit set means a producer needs something from us that we cannot provide, and we must refuse.

Functions

export

Serialize a tensor to a blob in the requested transport mode.

import

Reconstruct a tensor from a blob.

parse_header

Parse and validate a blob’s fixed header.

parse_planes

Parse count plane records from a planes region.

parse_strings

Parse the five strings from a strings region.

region_offsets

Derive every variable region’s offset from the fixed header.

strings_encoded_len

Encoded length of a strings region that begins start bytes into its blob, padded so the planes region that follows starts 8-aligned.

write_plane

Append one plane record to out, padded so the next record starts 8-aligned.

write_strings

Append the strings region to out, which holds the blob from its first byte, padded until out is a whole number of 8-byte words.