runtime/mapper.py

from pathlib import Path


class MemoryMapper:
    """Handles mmap-based zero-copy access to .gtkv files.

    The container file is mapped directly into virtual memory, avoiding
    read() syscalls for chunk index lookups and token payload access.
    Multiple views can be opened for parallel read.
    """
    def __init__(self, path: str):
        self._path = Path(path)
        self._map = None
        self._file = None

    def open(self):
        import mmap
        self._file = open(self._path, "rb")
        self._map = mmap.mmap(self._file.fileno(), 0, access=mmap.ACCESS_READ)

    def read(self, offset: int, size: int) -> bytes:
        if self._map is None:
            raise RuntimeError("memory map not open")
        return self._map[offset:offset + size]

    def close(self):
        if self._map:
            self._map.close()
        if self._file:
            self._file.close()

    @property
    def path(self) -> Path:
        return self._path

    @property
    def is_open(self) -> bool:
        return self._map is not None