Struct MasterIndex 

pub struct MasterIndex {
    pub disk_pages: Vec<PageEntry>,
    pub memory_pages: Vec<PageEntry>,
    pub disk_size: u64,
    pub memory_size: u64,
}

Top-level index stored at the end of a snapshot file.

The master index is the entry point for all random access operations. It contains separate page directories for disk and memory streams, plus logical size metadata for each stream.

Structure

• disk_pages: Index entries for the disk stream (persistent storage)
• memory_pages: Index entries for the memory stream (volatile state)
• disk_size: Total logical size of disk stream (uncompressed bytes)
• memory_size: Total logical size of memory stream (uncompressed bytes)

Location

The master index is always stored at the end of the snapshot file. Its offset is recorded in the snapshot header (header.index_offset).

Serialization

Serialized using bincode. Typical size: ~1KB per 1GB of data (with 64KB pages).

Random Access Algorithm

To read from disk stream at offset O:
1. page_idx = binary_search(master.disk_pages, |p| p.start_logical.cmp(&O))
2. page = read_and_deserialize(page_entry[page_idx])
3. block_info = find_block_in_page(page, O)
4. compressed = backend.read_exact(block_info.offset, block_info.length)
5. data = decompress(compressed)
6. return extract_range(data, O, len)

Dual Streams

Disk and memory streams are independently indexed. This enables:

• VM snapshots (disk = disk image, memory = RAM dump)
• Application snapshots (disk = state, memory = heap)
• Separate compression tuning per stream

Examples

use hexz_core::format::index::{MasterIndex, PageEntry};

let master = MasterIndex {
    disk_pages: vec![
        PageEntry {
            offset: 4096,
            length: 65536,
            start_block: 0,
            start_logical: 0,
        }
    ],
    memory_pages: vec![],
    disk_size: 1_000_000_000,  // 1GB logical
    memory_size: 0,
};

println!("Disk stream: {} GB", master.disk_size / (1024 * 1024 * 1024));
println!("Index pages: {}", master.disk_pages.len());

Fields

disk_pages: Vec<PageEntry>

Index pages for the disk stream.

memory_pages: Vec<PageEntry>

Index pages for the memory stream.

disk_size: u64

Total logical size of the disk stream (uncompressed bytes).

memory_size: u64

Total logical size of the memory stream (uncompressed bytes).

Implementations

impl MasterIndex

pub fn read_from<R: Read + Seek>( reader: &mut R, index_offset: u64, ) -> Result<Self>

Read master index by seeking to index_offset and reading to EOF.

pub fn read_from_bounded<R: Read + Seek>( reader: &mut R, index_offset: u64, length: u64, ) -> Result<Self>

Read master index with bounded length.

Trait Implementations

impl Clone for MasterIndex

fn clone(&self) -> MasterIndex

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MasterIndex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MasterIndex

fn default() -> MasterIndex

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for MasterIndex

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for MasterIndex

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.