bz2

bzip2 字节流、增量编解码、文件事务和进度回调。复用 bzip2 1.0.8 与 XRT，无额外压缩 DLL。

交付状态

2026-09-27：文件 OOM 修复已进入隔离候选，57 步专项通过，包含独立 C、JIT/AOT 故障注入；共享门禁覆盖两份 DLL 和纯 VFS。正式 release 尚未替换，不把候选通过当作所有发布物的完整 RC 验收。

快速使用

import bz2

Buffer packed = bz2.compress("你好，bz2", level = 6)
assert bz2.decompressText(packed, smallMemory = true) == "你好，bz2"

auto encoder = bz2.compressor()
encoder.update("left")
Buffer wire = encoder.drain()
encoder.update("right")
encoder.finish()
wire.append(encoder.drain())

接口

接口	用途与默认值
`compress(Buffer\|string, level=9, maxInput=268435456, maxOutput=536870912)`	输出 Buffer；字符串长度使用 UTF-8 字节数。
`decompress / decompressText`	smallMemory=false，maxInput=268435456，maxOutput=536870912，maxRatio=1000。
`compressor / decompressor`	增量对象；压缩 workFactor=30，合法范围 0..250。
`update / drain / finish`	finish 返回 bool，不移交输出；完成后仍需 drain，drain 不重置计数。
`valid / inputBytes / outputBytes / finished`	只读属性；解压器额外提供 members，finished 表示当前成员边界。
`compressFile / decompressFile`	source、destination、overwrite=true、限额及可选同步进度回调。

文件回调

bz2.compressFile("input.bin", "output.bz2",
    onProgress = func(int inputBytes, int totalBytes, int outputBytes) as bool
        println(inputBytes, "/", totalBytes)
        return true
    end)

返回 false 抛 CancelledError；回调异常保留类型和消息，最终通知也可取消。常规失败不覆盖已有目标，支持源目标同路径。冻结 XRT 的晚期 OOM 仍可能留下临时文件，修复同步前不作全失败路径保证。

格式、限额和错误

支持空内容、低内存解码、串联成员；拒绝 CRC 损坏、截断和尾部垃圾。非法压缩数据及文件错误为 IOError，参数错误为 ValueError，限额为 RangeError，状态错误为 RuntimeError，分配失败为 MemoryError。

同一对象串行使用。已 drain 的数据无法撤回；倍率按已提交输入计算，需同时设置 maxOutput。限额不是 CPU 超时或编解码器工作内存限制。CRC 不是加密认证。

C 同等能力

xrt_bz2.h 提供版本化 options/error、一次性 Buffer、增量对象、Reader/Writer、文件事务及 xrtprogressproc。C 可直接使用，不依赖 xlang；只链接一份 XRT/xruntime 与 bzip2。C 的零限额关闭对应限制，XL 便捷接口要求正数。

范例与验证

发行目录：examples/extlibs/bz2.xl、bz2_basic.xl、bz2_files.xl。C 对照位于 extlibs/bz2/examples/basic.c 和 files.c，两组使用相同输入与黄金输出。

源码门禁：tools/check_extlib_bz2.ps1、tools/check_extlib_bz2.sh；覆盖 23 个生成原型、269 项 Python bz2 互通、分配失败、IO/回调/状态边界、文件提交竞争及双语 JIT/AOT。Linux 检查范围为独立 C ASan/UBSan/泄漏测试，不代替 Linux xlang 验收。

完整签名、所有权和复验方式见包内 README.md。官网页描述的是已实现范围和已知限制，不承诺未验证的共享对象并发、性能或断电持久性。