Module zero_copy 

Zero-Copy Iterators - mmap-based Scans

This module provides memory-mapped file access for efficient, zero-copy iteration over large data files.

Design

┌─────────────────────────────────────────────────────────────────┐
│                    Zero-Copy Iterator                           │
│                                                                 │
│  Application                    OS/Kernel                       │
│  ┌────────────┐                 ┌────────────────────┐         │
│  │  Iterator  │                 │   Page Cache       │         │
│  │            │                 │  ┌──────────────┐  │         │
│  │  &[u8] ────┼─────────────────┼─▶│ Data Pages  │  │         │
│  │            │    mmap         │  └──────────────┘  │         │
│  └────────────┘                 │         ↑         │         │
│        │                        │         │         │         │
│        │ No copy!               │    ┌────┴────┐    │         │
│        ▼                        │    │  Disk   │    │         │
│  Process data                   │    └─────────┘    │         │
│  in-place                       └────────────────────┘         │
│                                                                 │
│  Benefits:                                                      │
│  • No buffer copies                                             │
│  • OS manages page faults                                       │
│  • Efficient for sequential scans                               │
│  • Read-ahead by OS                                             │
└─────────────────────────────────────────────────────────────────┘

Safety

Memory-mapped regions can become invalid if the underlying file is modified. This implementation provides:

• Read-only mappings by default
• Length validation
• Guard types for safe access

Structs

BlockIterator

Block-aware iterator that parses block headers

FilteredScan

Scanned region with optional filtering

IteratorStats

Iterator statistics

IteratorStatsSnapshot

MmapRegion

Memory-mapped region

ParallelScanConfig

Parallel scan configuration

RangeScanner

Range scanner for parallel processing

ZeroCopyIterator

Zero-copy iterator over chunks of mapped memory

Functions

open_for_scan

Open a file for zero-copy scanning

scan_file

Create an iterator over a file