Module spacetimedb_table::var_len

Provides the definitions of VarLenRef, VarLenGranule, and VarLenMembers.

We allocate variable-length objects within rows, e.g. strings and arrays, separately from the fixed-length parts of rows. The fixed-length part of the page starts at the top (offset 0) and grows downward, while the var-length part of the page starts at the bottom (largest offset) and grows upward.

Within the fixed-length part of the row, each var-len object is given a VarLenRef, which allows a mutator to locate the var-len object.

The var-length objects are BSATN-encoded to produce a bytestring (except strings, which are stored directly as UTF-8 bytestrings), and stored in a linked list of 64-byte “granules,” each of which has a 2-byte header and up to 62 bytes of data. This means that var-length objects never store padding bytes; every byte in a var-len object at an index less than the object’s length will be initialized.

At various points in the row’s lifecycle, we must visit all of the VarLenRefs within the row, e.g. to fix-up pointers when copying a row into a new page. This process is driven by a VarLenMembers visitor.

This file defines the representation of the linked list of granules VarLenGranule, the VarLenRef pointers to variable-length objects, and the trait VarLenMembers which visits VarLenRefs within a fixed-length row.

The broad strokes of var-len allocation are described in the Mem Arch Redesign proposal, ../../../../proposals/0001-mem-arch-redesign/mem-arch-redesign.md. Note that the proposal uses the words “blocks” or “chunks” where we use “granules.”

Structs

• AlignedVarLenOffsets
  Slice of offsets to var-len members, in units of 2-byte words.
• AlignedVarLenOffsetsIter
• AlignedVarLenOffsetsIterMut
• NullVarLenVisitor
  A VarLenMembers visitor for row types with no var-len components, which never visits anything.
• VarLenGranule
  Each variable length object in a page is stored as a linked-list of chunks. These chunks are called granules and they can store up to 62 bytes of data. Additionally, 2 bytes are used for the header: VarLenGranuleHeader.
• VarLenGranuleHeader
  The header of a VarLenGranule storing
• VarLenRef
  Reference to var-len object within a page.

Traits

• VarLenMembers
  A visitor object which can iterate over the var-len slots in a row.

Functions

• is_granule_offset_aligned
  Returns whether offset is properly aligned for storing a VarLenGranule.
• visit_var_len_assume_init^⚠
  Treat init_row as storage for a row of the particular type handled by visitor, and iterate over the assumed-to-be initialized VarLenRefs within it.