BlockTable

Models & Types · AiDotNet.Inference.PagedAttention

Maps logical block indices to physical block IDs for a sequence.

For Beginners

Think of the block table like a book’s table of contents.

The book (your sequence) has logical chapters (logical blocks) numbered 0, 1, 2… But the actual pages (physical blocks) might be scattered throughout the library. The table of contents tells you: “Chapter 0 is on shelf A, Chapter 1 is on shelf Z…”

This indirection allows:

  • Efficient memory allocation (use any available block)
  • Copy-on-write for beam search (share chapters between book copies)
  • Swapping to disk (move a chapter to storage, update the table)

How It Works

The BlockTable provides the indirection layer between logical sequence positions and physical memory blocks. Each sequence has its own block table that grows as more tokens are generated.

Constructors

Constructor Summary
BlockTable(long sequenceId, int blockSize) Creates a new block table for a sequence.
BlockTable(long sequenceId, int blockSize, IEnumerable<int> physicalBlockIds) Creates a new block table with pre-allocated blocks.

Properties

Property Summary
IReadOnlyList<int> PhysicalBlockIds { get; } Gets the physical block IDs as a read-only list.
int BlockSize { get; } Gets the block size (tokens per block).
int Capacity { get; } Gets the total token capacity.
int NumLogicalBlocks { get; } Gets the number of logical blocks in this table.
long SequenceId { get; } Gets the sequence ID this table belongs to.

Methods

Method Summary
BlockTable Copy(long newSequenceId) Creates a copy of this block table (shallow copy - shares block IDs).
List<int> Clear() Clears all blocks from the table.
List<int> TruncateTo(int numBlocks) Truncates the table to the specified number of logical blocks.
ValueTuple<int, int> GetBlockAndOffset(int tokenPosition) Gets the physical block ID and offset for a token position.
bool HasCapacityFor(int currentLength) Checks if the table has capacity for additional tokens.
int AdditionalBlocksNeeded(int currentTokens, int additionalTokens) Calculates how many additional blocks are needed for more tokens.
int BlocksNeededFor(int numTokens) Calculates how many blocks are needed for a given number of tokens.
int GetPhysicalBlock(int logicalIndex) Gets the physical block ID for a logical block index.
int RemoveLastBlock() Removes the last block from the table.
int ReplaceBlock(int logicalIndex, int newPhysicalBlockId) Replaces a physical block ID at the specified logical index.
int[] ToArray() Gets the physical block IDs as an array (useful for GPU transfer).
string ToString() Returns a string representation of the block table.
void AppendBlock(int physicalBlockId) Appends a new physical block to the table.
void AppendBlocks(IEnumerable<int> physicalBlockIds) Appends multiple physical blocks to the table.