rustgzip 0.5.2__py3-none-win_amd64.whl

rustgzip/__init__.py

@@ -0,0 +1,385 @@
+# -*- coding: utf-8 -*-
+"""Rust 加速的 gzip 文件接口；Python 3.4+，运行时只依赖标准库。
+
+压缩和 CRC 校验全部由包内动态库完成。文件接口使用固定大小缓冲，
+不会因为读取一个大 gzip 文件就自动把整个文件载入内存。
+"""
+from __future__ import absolute_import
+
+import ctypes
+import codecs
+import io
+import operator
+import os
+import sys
+import threading
+
+__version__ = '0.5.2'
+__all__ = ['open', 'compress', 'decompress', 'decompress_into', 'verify', 'GzipFile', 'backend_info']
+_BUFFER = 256 * 1024
+_LIB = None
+_LOAD_LOCK = threading.Lock()
+
+
+def _library():
+    """只加载随包交付的库，不从工作目录或 PATH 猜测同名动态库。"""
+    global _LIB
+    # 加载成功后的热路径不再竞争全局锁；首次加载仍在锁内二次检查。
+    if _LIB is not None:
+        return _LIB
+    with _LOAD_LOCK:
+        if _LIB is not None:
+            return _LIB
+        filename = ('rustgzip_native.dll' if sys.platform == 'win32'
+                    else 'librustgzip_native.so')
+        path = os.path.join(os.path.dirname(os.path.abspath(__file__)), filename)
+        try:
+            lib = ctypes.CDLL(path)
+        except OSError as exc:
+            raise ImportError('无法加载 Rust gzip 动态库；请安装匹配系统架构的完整包：%s' % exc)
+        # 先验证 ABI 再绑定新增函数。混用旧动态库时给出明确提示，而不是找符号失败。
+        try:
+            lib.rg_abi_version.restype = ctypes.c_uint32
+            lib.rg_abi_version.argtypes = []
+            if lib.rg_abi_version() != 4:
+                raise ImportError('Rust gzip 动态库接口版本不匹配，请重新安装完整包')
+        except AttributeError:
+            raise ImportError('Rust gzip 动态库缺少版本接口，请重新安装完整包')
+        size = ctypes.c_size_t
+        ptr = ctypes.c_void_p
+        error = [ptr, size]
+        signatures = {
+            'rg_abi_version': (ctypes.c_uint32, []),
+            'rg_open': (ctypes.c_int, [ptr, size, ctypes.c_int, ctypes.c_uint32,
+                                    ctypes.POINTER(ctypes.c_uint64)] + error),
+            'rg_read': (ctypes.c_int64, [ctypes.c_uint64, ptr, size] + error),
+            'rg_write': (ctypes.c_int64, [ctypes.c_uint64, ptr, size] + error),
+            'rg_flush': (ctypes.c_int, [ctypes.c_uint64] + error),
+            'rg_verify': (ctypes.c_int64, [ctypes.c_uint64, size] + error),
+            'rg_close': (ctypes.c_int, [ctypes.c_uint64] + error),
+            'rg_transform': (ctypes.c_int, [ptr, size, ctypes.c_int, ctypes.c_uint32,
+                size, ctypes.POINTER(ptr), ctypes.POINTER(size), ctypes.POINTER(size)] + error),
+            'rg_free': (None, [ptr, size, size]),
+            'rg_decompress_into': (ctypes.c_int64, [ptr, size, ptr, size] + error),
+        }
+        for name, signature in signatures.items():
+            try:
+                function = getattr(lib, name)
+            except AttributeError:
+                raise ImportError('Rust gzip 动态库缺少接口 %s，请重新安装完整包' % name)
+            function.restype, function.argtypes = signature
+        _LIB = lib
+        return lib
+
+
+def _call(name, *args):
+    """每次调用独立错误缓冲；CDLL 在原生计算期间会释放 Python GIL。"""
+    err = ctypes.create_string_buffer(2048)
+    try:
+        result = getattr(_library(), name)(*(args + (err, len(err))))
+    finally:
+        # 异常的 traceback 可能长期保留本帧。不要让参数元组继续持有 ctypes
+        # from_buffer 导出的视图，否则用户在 except 中扩容 bytearray 会失败。
+        args = ()
+    if result == -1:
+        detail = err.value.decode('utf-8', 'replace')
+        raise OSError('gzip 操作失败：%s' % detail)
+    return result
+
+
+def _level(value):
+    value = operator.index(value)
+    if not 0 <= value <= 9:
+        raise ValueError('compresslevel 必须是 0 到 9 的整数')
+    return value
+
+
+def _bytes(data):
+    """接受缓冲协议，拒绝整数和字符串，避免 bytes(整数) 意外分配大内存。"""
+    # bytes 子类可以覆盖 __len__；跨 FFI 传长度前必须规范成真正的 bytes，
+    # 否则长度和底层分配空间可能不一致。普通 bytes 仍走不复制的快路径。
+    if type(data) is bytes:
+        return data
+    return memoryview(data).tobytes()
+
+
+class _RawGzip(io.RawIOBase):
+    """一个 Rust 文件流。锁保护同一对象，独立文件流可以并发工作。
+
+    handle 是编号，不是指针；所有退出路径都通过 rg_close 释放 Rust 资源。
+    不支持 seek、fileobj 或 fileno；避免把压缩文件偏移误当成解压后偏移。
+    """
+    def __init__(self, filename, mode, compresslevel):
+        super(_RawGzip, self).__init__()
+        self._lock = threading.RLock()
+        self._handle = 0
+        self._mode = mode
+        self.name = filename
+        self._position = 0
+        # Python 3.4 没有 os.fspath；直接支持 str/bytes，并兼容较新版 Path。
+        if not isinstance(filename, (str, bytes)):
+            if not hasattr(filename, '__fspath__'):
+                raise TypeError('filename 必须是路径 str/bytes/Path，不支持 fileobj')
+            filename = filename.__fspath__()
+            if not isinstance(filename, (str, bytes)):
+                raise TypeError('__fspath__ 必须返回 str 或 bytes')
+        if isinstance(filename, str):
+            path = filename.encode('utf-8') if sys.platform == 'win32' else os.fsencode(filename)
+        elif sys.platform == 'win32':
+            path = os.fsdecode(filename).encode('utf-8')
+        else:
+            path = filename
+        path = _bytes(path)
+        if b'\0' in path:
+            raise ValueError('文件路径不能包含 NUL 字符')
+        allocated = ctypes.c_uint64()
+        try:
+            _call('rg_open', path, len(path), 'rwax'.index(mode), _level(compresslevel),
+                  ctypes.byref(allocated))
+            self._handle = allocated.value
+        except BaseException:
+            # 包括 KeyboardInterrupt。输出参数在原生函数返回前已经写好，
+            # 因此不必等析构/垃圾回收，也能关闭“刚打开就被中断”的文件。
+            self._handle = 0
+            if allocated.value:
+                try:
+                    _call('rg_close', allocated.value)
+                except Exception:
+                    pass  # 保留引发清理的原始异常；句柄已由原生 close 移除。
+            raise
+
+    @property
+    def mode(self):
+        return self._mode + 'b'
+
+    def readable(self):
+        self._checkClosed()
+        return self._mode == 'r'
+
+    def writable(self):
+        self._checkClosed()
+        return self._mode != 'r'
+
+    def tell(self):
+        self._checkClosed()
+        return self._position
+
+    def readinto(self, buffer):
+        with self._lock:
+            self._checkClosed()
+            if not self.readable():
+                raise io.UnsupportedOperation('当前文件不可读')
+            view = memoryview(buffer)
+            byte_view, native = None, None
+            try:
+                byte_view = view.cast('B')
+                if not len(byte_view):
+                    return 0
+                # 直接向调用方提供的可写缓冲填充结果，不创建完整返回副本。
+                native = (ctypes.c_ubyte * len(byte_view)).from_buffer(byte_view)
+                count = _call('rg_read', self._handle, native, len(byte_view))
+                self._position += count
+                return count
+            finally:
+                native = None  # 先释放 ctypes 自己导出的视图，再释放外层 memoryview。
+                if byte_view is not None:
+                    byte_view.release()
+                view.release()
+
+    def readall(self):
+        # RawIOBase 默认小块循环会增加 FFI 次数，这里按 1 MiB 读取。
+        parts = []
+        while True:
+            part = self.read(1024 * 1024)
+            if not part:
+                return b''.join(parts)
+            parts.append(part)
+
+    def write(self, data):
+        with self._lock:
+            self._checkClosed()
+            if not self.writable():
+                raise io.UnsupportedOperation('当前文件不可写')
+            data = _bytes(data)
+            count = _call('rg_write', self._handle, data, len(data))
+            self._position += count
+            return count
+
+    def flush(self):
+        with self._lock:
+            self._checkClosed()
+            # 读流没有待写数据。尤其不能让 close 中的 flush 覆盖原始 CRC 错误。
+            if self._handle and self.writable():
+                _call('rg_flush', self._handle)
+
+    def close(self):
+        # IOBase.close 会先 flush。无论 flush 是否失败，finally 都要关闭原生句柄。
+        lock = getattr(self, '_lock', None)
+        if lock is None:
+            return
+        with lock:
+            if self.closed and not self._handle:
+                return
+            try:
+                if not self.closed:
+                    super(_RawGzip, self).close()
+            finally:
+                handle = self._handle
+                if handle:
+                    try:
+                        _call('rg_close', handle)
+                    except BaseException:
+                        # Ctrl+C 可能在 Python 已标记 closed、但尚未进入原生
+                        # close 时到达。补做一次清理；若原生端早已移除编号，
+                        # 重复关闭的“无效编号”会被忽略，保留第一次异常。
+                        # 编号单调递增而不复用，所以不会误关闭另一个文件。
+                        try:
+                            _call('rg_close', handle)
+                        except BaseException:
+                            pass
+                        raise
+                    finally:
+                        self._handle = 0
+
+
+class _BufferedGzipWriter(io.BufferedWriter):
+    """把公开 flush 一直传递到 gzip 编码器和底层文件缓冲。
+
+    标准 BufferedWriter 只保证把自身数据交给 raw.write；本包 raw 层还包含
+    Rust 压缩器和文件缓冲，所以这里需要显式继续 flush，不代表 fsync。
+    """
+    def flush(self):
+        super(_BufferedGzipWriter, self).flush()
+        self.raw.flush()
+
+
+def open(filename, mode='rb', compresslevel=6, encoding=None, errors=None,
+         newline=None, buffering=_BUFFER):
+    """打开路径形式的 gzip 文件，支持 rb/wb/ab/xb 及 rt/wt/at/xt。
+
+    返回标准 BufferedReader / BufferedWriter / TextIOWrapper，可迭代、readinto、
+    read、readline、write 和 with 自动关闭。读到 EOF 时才完成各 member 的 CRC 校验。
+    默认压缩级别 6；只支持顺序流，不宣称完整替代标准库 gzip 的所有扩展行为。
+    """
+    if not isinstance(mode, str) or mode not in (
+            'r', 'rb', 'rt', 'w', 'wb', 'wt', 'a', 'ab', 'at', 'x', 'xb', 'xt'):
+        raise ValueError('mode 必须为 rb/wb/ab/xb 或 rt/wt/at/xt')
+    binary = 't' not in mode
+    if binary and any(v is not None for v in (encoding, errors, newline)):
+        raise ValueError('二进制模式不能指定 encoding/errors/newline')
+    buffering = operator.index(buffering)
+    if buffering <= 0:
+        raise ValueError('buffering 必须大于 0')
+    if buffering > sys.maxsize:
+        raise OverflowError('buffering 超出当前 Python 可表示的缓冲长度')
+    if not binary:
+        # 在任何可能创建/截断文件的操作之前校验文本参数。错误编码或 newline
+        # 不应让一个尚未成功打开的调用破坏原文件。BytesIO 探针不访问磁盘。
+        probe = io.TextIOWrapper(io.BytesIO(), encoding=encoding, errors=errors, newline=newline)
+        try:
+            codecs.lookup_error(probe.errors)
+        finally:
+            probe.close()
+    raw = _RawGzip(filename, mode[0], compresslevel)
+    stream = None
+    try:
+        stream = (io.BufferedReader(raw, buffering) if mode[0] == 'r'
+                  else _BufferedGzipWriter(raw, buffering))
+        if binary:
+            return stream
+        return io.TextIOWrapper(stream, encoding=encoding, errors=errors, newline=newline)
+    except BaseException:
+        (stream or raw).close()
+        raise
+
+
+def GzipFile(filename=None, mode='rb', compresslevel=6, **kwargs):
+    """常用路径式 GzipFile 入口；不接受 fileobj/mtime 参数，也不是标准库同名类。"""
+    return open(filename, mode, compresslevel, **kwargs)
+
+
+def _transform(data, decode, level, limit):
+    data = _bytes(data)
+    output = ctypes.c_void_p()
+    length = ctypes.c_size_t()
+    capacity = ctypes.c_size_t()
+    lib = _library()
+    try:
+        # 必须连原生调用本身也放入 try：C 已分配返回缓冲之后，Python 可能
+        # 在下一条字节码前处理 Ctrl+C，此时也要使用输出参数执行配对释放。
+        _call('rg_transform', data, len(data), decode, _level(level), limit,
+              ctypes.byref(output), ctypes.byref(length), ctypes.byref(capacity))
+        return ctypes.string_at(output, length.value)
+    finally:
+        # string_at 返回 Python 自有副本，原生分配随后释放，不能交给 Python 的 free。
+        if output.value:
+            lib.rg_free(output, length.value, capacity.value)
+
+
+def compress(data, compresslevel=6):
+    """将 bytes-like 压缩为标准 gzip，固定时间戳 0，不嵌入文件名。"""
+    return _transform(data, 0, compresslevel, 0)
+
+
+def decompress(data, max_output_size=512 * 1024 * 1024):
+    """内存解压，支持串接 member；默认最多输出 512 MiB，可显式调整。
+
+    超过上限或 CRC/长度/格式错误直接抛出 OSError，不返回部分成功结果。
+    大文件建议使用 open 分块读取，以保持内存稳定。
+    """
+    limit = operator.index(max_output_size)
+    if not 0 <= limit < sys.maxsize:
+        raise ValueError('max_output_size 必须在 0 到 sys.maxsize-1 之间')
+    return _transform(data, 1, 6, limit)
+
+
+def decompress_into(data, output):
+    """完整解压到调用方已有的可写连续缓冲，返回有效字节数。
+
+    output 可以是 bytearray 或可写的连续 memoryview；容量就是输出上限。
+    不创建完整的 Rust 输出 Vec，也不创建一个额外的 Python bytes 副本。
+    只在成功验证所有 member 的 CRC/长度及 EOF 后返回。失败时 output
+    可能已被部分改写，必须丢弃其内容。调用期间其他线程不可访问此缓冲。
+    """
+    data = _bytes(data)
+    view = memoryview(output)
+    byte_view, native = None, None
+    try:
+        if view.readonly:
+            raise TypeError('output 必须是可写缓冲，例如 bytearray')
+        if not view.c_contiguous:
+            raise ValueError('output 必须是 C 连续缓冲，不能使用跨步切片')
+        byte_view = view.cast('B')
+        if not len(byte_view):
+            return _call('rg_decompress_into', data, len(data), None, 0)
+        native = (ctypes.c_ubyte * len(byte_view)).from_buffer(byte_view)
+        return _call('rg_decompress_into', data, len(data), native, len(byte_view))
+    finally:
+        native = None
+        if byte_view is not None:
+            byte_view.release()
+        view.release()
+
+
+def verify(filename, chunk_size=1024 * 1024):
+    """完整读取并校验 gzip，返回解压后的字节总数，不写出解压文件。
+
+    循环和复用缓冲都在 Rust 内部，适合“逐块读取直到末尾”的完整性检查场景。
+    chunk_size 可选 1 字节到 64 MiB；校验函数不保存解压后的内容。
+    """
+    chunk_size = operator.index(chunk_size)
+    if not 1 <= chunk_size <= 64 * 1024 * 1024:
+        raise ValueError('chunk_size 必须在 1 字节到 64 MiB 之间')
+    with _RawGzip(filename, 'r', 6) as raw:
+        return _call('rg_verify', raw._handle, chunk_size)
+
+
+def backend_info():
+    """加载后端并返回诊断信息；不会上传路径、数据或环境信息。"""
+    return {'package_version': __version__, 'abi_version': _library().rg_abi_version(),
+            'backend': 'flate2 1.1.10 / zlib-rs', 'python': sys.version.split()[0],
+            'memory_decoder': 'zlib-rs direct for simple headers; flate2 fallback',
+            'member_state_reuse': True,
+            'experimental_parallel_compression': hasattr(_library(), 'rg_compress_parallel'),
+            'experimental_parallel_compression_into': hasattr(_library(), 'rg_compress_parallel_into'),
+            'parallel_single_member_decode': False}

rustgzip/experimental.py

@@ -0,0 +1,283 @@
+# -*- coding: utf-8 -*-
+"""显式启用的并行实验，兼容 Python 3.4；不改变主模块默认行为。
+
+compress_parallel 把压缩分到 Rust 工作线程，生成一个普通 gzip member。
+prefetch 只有一个解码线程，作用是把解压与调用方处理重叠，不是并行解码。
+"""
+from __future__ import absolute_import
+import ctypes
+import operator
+import queue
+import threading
+from . import _call, _level, _library, open as gzip_open
+
+_BIND_LOCK = threading.Lock()
+_MAX_INPUT_SIZE = 512 * 1024 * 1024
+
+
+def _bounded_bytes(data):
+    """先按真实缓冲大小拒绝超限输入，避免先复制数百 MiB 才报错。
+
+    不调用对象可覆盖的 __len__；bytes 子类和跨步视图也按实际 nbytes 校验。
+    原始 bytes 保留不复制路径，其它缓冲在持有视图期间复制，之后及时释放视图。
+    """
+    if type(data) is bytes:
+        if len(data) > _MAX_INPUT_SIZE:
+            raise ValueError('实验接口输入不能超过 512 MiB；大文件请继续使用 open')
+        return data
+    view = memoryview(data)
+    try:
+        if view.nbytes > _MAX_INPUT_SIZE:
+            raise ValueError('实验接口输入不能超过 512 MiB；大文件请继续使用 open')
+        return view.tobytes()
+    finally:
+        view.release()
+
+
+def _options(data, compresslevel, workers, chunk_size, use_dictionary):
+    """两个压缩入口共用校验，避免 into 接口遗漏输入大小或参数限制。"""
+    workers, chunk_size = operator.index(workers), operator.index(chunk_size)
+    if not 1 <= workers <= 32:
+        raise ValueError('workers 必须在 1 到 32 之间')
+    if not 32768 <= chunk_size <= 16 * 1024 * 1024:
+        raise ValueError('chunk_size 必须在 32 KiB 到 16 MiB 之间')
+    if type(use_dictionary) is not bool:
+        raise TypeError('use_dictionary 必须是 bool')
+    level = _level(compresslevel)
+    data = _bounded_bytes(data)
+    return data, level, workers, chunk_size
+
+
+def compress_parallel(data, compresslevel=6, workers=2, chunk_size=1024 * 1024,
+                      use_dictionary=True):
+    """内存并行压缩；返回标准单 member gzip，不要求特殊解码器或外部字典。
+
+    workers 范围 1..32，chunk_size 范围 32 KiB..16 MiB，输入至多 512 MiB。
+    默认后块预置前 32 KiB 原文。禁用字典只用于对照，不保证压缩率不变。
+    整体输入和结果仍在内存；不是大文件流式写入接口。异常不返回部分结果。
+    """
+    data, level, workers, chunk_size = _options(data, compresslevel, workers, chunk_size, use_dictionary)
+    lib = _library()
+    # 这是对 ABI 4 的可选扩展，不更改旧函数。旧 0.3.1 动态库仍可供
+    # 主 API 使用；使用本实验接口时缺少新符号，则明确要求安装完整新包。
+    with _BIND_LOCK:
+        try:
+            function = lib.rg_compress_parallel
+        except AttributeError:
+            raise ImportError('当前动态库不含并行实验，请安装完整 0.4.0 包并重启 Python')
+        function.restype = ctypes.c_int
+        ptr, size = ctypes.c_void_p, ctypes.c_size_t
+        function.argtypes = [ptr, size, ctypes.c_uint32, size, size, ctypes.c_int,
+                             ctypes.POINTER(ptr), ctypes.POINTER(size),
+                             ctypes.POINTER(size), ptr, size]
+    output, length, capacity = ctypes.c_void_p(), ctypes.c_size_t(), ctypes.c_size_t()
+    try:
+        _call('rg_compress_parallel', data, len(data), level, workers, chunk_size,
+              int(use_dictionary), ctypes.byref(output), ctypes.byref(length),
+              ctypes.byref(capacity))
+        return ctypes.string_at(output, length.value)
+    finally:
+        if output.value:
+            lib.rg_free(output, length.value, capacity.value)
+
+
+def compress_parallel_into(data, output, compresslevel=6, workers=2,
+                           chunk_size=1024 * 1024, use_dictionary=True):
+    """直接压缩到已有可写连续缓冲，返回有效字节数，减少完整结果的分配与复制。
+
+    参数限制与 compress_parallel 相同。output 的容量由调用方预留；不足时
+    抛出 OSError 并说明实际需要大小，可扩容后重试，但本次压缩计算不能复用。
+    只使用成功返回的 [:count]；尾部不改写。失败/中断后不把缓冲视为有效结果。
+    调用期间其他线程不得读写/扩容 output；持有自己的 memoryview 也会限制扩容。
+    """
+    data, level, workers, chunk_size = _options(data, compresslevel, workers, chunk_size, use_dictionary)
+    lib = _library()
+    with _BIND_LOCK:
+        try:
+            function = lib.rg_compress_parallel_into
+        except AttributeError:
+            raise ImportError('当前动态库不含压缩 into 接口，请安装完整 0.5.0 包并重启 Python')
+        function.restype = ctypes.c_int64
+        ptr, size = ctypes.c_void_p, ctypes.c_size_t
+        function.argtypes = [ptr, size, ctypes.c_uint32, size, size, ctypes.c_int,
+                             ptr, size, ptr, size]
+    view = memoryview(output)
+    byte_view, native = None, None
+    try:
+        if view.readonly:
+            raise TypeError('output 必须是可写缓冲，例如 bytearray')
+        if not view.c_contiguous:
+            raise ValueError('output 必须是 C 连续缓冲')
+        byte_view = view.cast('B')
+        if len(byte_view):
+            native = (ctypes.c_ubyte * len(byte_view)).from_buffer(byte_view)
+        return _call('rg_compress_parallel_into', data, len(data), level, workers,
+                     chunk_size, int(use_dictionary), native, len(byte_view))
+    finally:
+        # 包括异常 traceback 仍被用户保留的情况，必须解除本接口持有的导出。
+        native = None
+        if byte_view is not None:
+            byte_view.release()
+        view.release()
+
+
+class _PrefetchedChunks(object):
+    """只在 with 期间拥有工作线程与文件；提前退出也会取消并 join。
+
+    队列最多保存 queue_depth 个不可变 bytes；另外允许生产/消费各持有一块。
+    不在调用线程关闭仍被工作线程读取的 raw，避免 close/read 锁竞争。
+    close 会等待当前原生 read 返回，不能强行取消阻塞的网络文件系统 I/O。
+    同一个对象仅供一个消费线程使用，不支持重复进入或跨线程 close。
+    """
+    def __init__(self, filename, chunk_size, queue_depth):
+        self.filename = filename
+        self.chunk_size = operator.index(chunk_size)
+        self.queue_depth = operator.index(queue_depth)
+        if not 1 <= self.chunk_size <= 16 * 1024 * 1024:
+            raise ValueError('chunk_size 必须在 1 字节到 16 MiB 之间')
+        if not 1 <= self.queue_depth <= 16:
+            raise ValueError('queue_depth 必须在 1 到 16 之间')
+        self._queue = queue.Queue(self.queue_depth)
+        self._stop = threading.Event()
+        # 不单凭 Thread.is_alive / join 的状态认定资源已释放；读取线程在
+        # finally 中关闭文件后才置位，主线程被 Ctrl+C 中断也不能越过此屏障。
+        self._done = threading.Event()
+        self._thread = None
+        self._entered = False
+        self._closed = False
+        self._ended = False
+        self._owner = None
+
+    def _send(self, item):
+        # put 不能永久阻塞，否则调用方提前 break 时 close.join 会死锁。
+        while not self._stop.is_set():
+            try:
+                self._queue.put(item, timeout=0.05)
+                return
+            except queue.Full:
+                pass
+
+    def _produce(self):
+        try:
+            if self._stop.is_set():
+                return  # start 中断后才获得调度的线程，不再打开文件。
+            with gzip_open(self.filename, 'rb') as source:
+                while not self._stop.is_set():
+                    block = source.read(self.chunk_size)
+                    if not block:
+                        break
+                    self._send((block, None))
+            self._send((None, None))
+        except BaseException as exc:
+            # 不跨线程保留 traceback 的 source/大缓冲；下一次 next 原样报错。
+            if isinstance(exc, StopIteration):
+                # 迭代器协议会把 StopIteration 当成正常 EOF。路径/读取钩子
+                # 的意外 StopIteration 必须转换，不能让损坏的读取流程假成功。
+                exc = RuntimeError('预取读取意外抛出 StopIteration：%s' % exc)
+            self._send((None, exc.with_traceback(None)))
+        finally:
+            self._done.set()
+
+    def __enter__(self):
+        if self._entered or self._closed:
+            raise RuntimeError('prefetch 对象只能在一个 with 中使用一次')
+        self._entered = True
+        self._owner = threading.current_thread().ident
+        try:
+            self._thread = threading.Thread(target=self._produce, name='rustgzip-prefetch')
+            self._thread.daemon = True
+            self._thread.start()
+        except BaseException:
+            # start 可能已经启动线程，随后才收到 Ctrl+C；按 ident 判断是否 join。
+            self._stop.set()
+            if self._thread is not None and self._thread.ident is not None:
+                self.close()
+            else:
+                self._closed = True
+            raise
+        return self
+
+    def _check_owner(self):
+        if not self._entered:
+            raise RuntimeError('请使用 with prefetch(...) as chunks')
+        if threading.current_thread().ident != self._owner:
+            raise RuntimeError('prefetch 只能由进入 with 的线程消费和关闭')
+
+    def __iter__(self):
+        self._check_owner()
+        return self
+
+    def __next__(self):
+        self._check_owner()
+        if self._closed or self._ended:
+            raise StopIteration
+        while True:
+            try:
+                block, error = self._queue.get(timeout=0.05)
+                break
+            except queue.Empty:
+                if self._done.is_set():
+                    # Queue.get 超时与 is_alive 之间仍可能刚好入队并结束。
+                    # 再检查一次队列，避免把已经到达的 EOF/错误误判为线程丢失。
+                    try:
+                        block, error = self._queue.get_nowait()
+                        break
+                    except queue.Empty:
+                        raise RuntimeError('预取工作线程意外终止，不能视为正常 EOF')
+        if block is None:
+            self._ended = True
+            if error is not None:
+                raise error
+            raise StopIteration
+        return block
+
+    def close(self):
+        if not self._entered:
+            self._closed = True
+            return
+        self._check_owner()
+        if self._closed:
+            return
+        self._stop.set()
+        interrupted = None
+        if self._thread is not None and self._thread.ident is not None:
+            # Ctrl+C 先记住，等源文件退出 with 并释放队列后再向调用方抛出。
+            # Event.wait 不会因 join 的中断而误报“工作线程已经退出”。
+            while not self._done.is_set():
+                try:
+                    self._done.wait(0.05)
+                except KeyboardInterrupt as exc:
+                    if interrupted is None:
+                        interrupted = exc.with_traceback(None)
+            while True:
+                try:
+                    self._thread.join()
+                    break
+                except KeyboardInterrupt as exc:
+                    if interrupted is None:
+                        interrupted = exc.with_traceback(None)
+        while True:
+            try:
+                self._queue.get_nowait()
+            except queue.Empty:
+                break
+            except KeyboardInterrupt as exc:
+                if interrupted is None:
+                    interrupted = exc.with_traceback(None)
+        self._closed = True
+        if interrupted is not None:
+            raise interrupted
+
+    def __exit__(self, exc_type, exc, traceback):
+        self.close()
+        return False
+
+
+def prefetch(filename, chunk_size=1024 * 1024, queue_depth=2):
+    """with prefetch(path) as chunks: 按顺序迭代解压块。
+
+    读到迭代结束才完成 CRC/长度检查。提前 break 仅取消读取，不宣称已验证
+    全文件；close 不自动读取尾部。队列等待释放 GIL，纯 Python CPU 循环的
+    业务代码仍受 GIL 限制，实际收益必须用自己的数据和处理逻辑测量。
+    """
+    return _PrefetchedChunks(filename, chunk_size, queue_depth)