snappy

压缩归档

2026-10-30 修复标准空数据块误拒绝：Windows/Linux 同一 C 回归 379 场景、10 个真实 XRT OOM，旧源 352 条失败断言变为 0。26 个实际桥接声明、新旧双语及各 13 条正常 AOT 通过；默认门禁最后仍因 M2 顶层对象退役返回 1，不作整包发布签收，也不提前销毁或移动全局对象绕开。

2026-10-31 修四条 C Reader/Writer 错误结构丢失首因，30 场景同夹具两平台旧32条断言失败→0；保留原始错误对象。打开态文件双故障96组Win旧8红→0，关闭态仍两组残留（RFS）。新旧双语、实际ABI、各17条普通AOT与独立格式互通过；默认Win88阶段86符合，最后RFS/M2分别失败，Linux此轮只剩M2，不作整包签收。

v1.0.0C 混编0 依赖ABI 1

标准 Snappy framed stream 压缩。纯 C codec 与 xlang API 提供二进制安全的 Buffer 一次性、文件及 update → drain → finish 增量流式处理；输出可与遵循官方 framing 格式的工具互通。

典型场景

大数据管道实时流压缩缓存压缩RPC 载荷日志压缩进度回显传输

快速开始

quick_start.xl
import snappy

func main(...) as int
    Buffer packed = snappy.compress("hello snappy")
    println(snappy.decompressText(packed))   // hello snappy

    auto enc = snappy.compressor()
    enc.update("part1 ")
    enc.update("part2")
    enc.finish()
    Buffer blob = enc.drain()

    auto dec = snappy.decompressor()
    dec.update(blob)
    dec.finish()
    println(dec.drain().text())           // part1 part2
    return 0
end

核心特性

2026-10-28：C 桥接头可单独或与核心/XRT 头按任意顺序包含，不改变宿主的模块选择。Windows/Linux 的四种严格 C 编译与基础 C/XL 范例 JIT/AOT 同输出通过；本次只调整声明，未重复完整算法和压力门禁。

标准 framing — 产出符合 Google Snappy framed stream 格式的 .sz 数据
块校验 — 使用 masked CRC32C；损坏的块会被拒绝
标准空块 — 接受 CRC 正确的空正文，继续校验 raw 压缩指令与 framing；空块不是 EOF
二进制安全 — 输入输出统一 Buffer
三种粒度 — 一次性内存、文件级、增量流式（SnappyCompressor/SnappyDecompressor）
真流式输出 — drain() 随时取走已产出字节
分段输入 — 压缩按 64 KiB 原文块处理；解压的大输入分段解析，可跳过 chunk 不缓存主体
进度回显 — inputBytes/outputBytes 字节计数器
串联流 — members 统计 stream identifier；C 选项的 iMaxEntries 限制其数量，finished 表示 finish() 成功
文件提交 — 同目录临时文件，处理与flush/close成功才重命名；Windows关闭态回滚OOM仍开放，不等于断电持久性保证

包信息

包名	snappy
版本	1.0.0
引擎	纯 C Snappy 格式兼容实现 1.0.0
实现方式	C 混编（Snappy 引擎 C，API 层 xlang）
依赖	无
ABI 版本	1
导出符号	compress(), decompress(), decompressText(), compressFile(), decompressFile(), compressor(), decompressor(), SnappyCompressor, SnappyDecompressor
源文件	extlibs/snappy/src/snappy.xl

一次性 / 文件 / 流式

export func compress(Buffer data, ...) as Buffer export func decompress(Buffer data, ...) as Buffer export func compressFile(...) / decompressFile(...) export func compressor(...) as SnappyCompressor export func decompressor(...) as SnappyDecompressor

提供一次性、文件级、增量流式三种接口。流式类提供 update/drain/finish + inputBytes/outputBytes/finished/members。framing 没有结束标记：不完整的末尾 chunk 会报错，但无法检测完整 chunk 边界处的提前终止。

文件接口末尾支持可空 onProgress(inputBytes, totalBytes, outputBytes)，false 取消，回调错误保留首因；含 NUL 路径报 ValueError。native 文件 ABI 使用 XRT callable（三个 uint64、bool返回，无FINAL参数），普通 C Reader/Writer 流才用 xrtprogressproc + userData。C 流进度从 Reader 当前位置起算，无法同时取得总长/当前位置时不置 TOTAL_KNOWN。Windows 关闭态回滚 OOM 缺口仍在。

C 的 Reader 失败和 drain Writer 失败保留可识别参数、内存、限额、状态、取消或 IO 类别，以及原始 backend、消息和生成计数；XRT 首错对象不替换。调用方持有的 Reader/Writer 不被 codec 关闭；生成计数不等于已交付字节。

Snappy 为固定策略算法，无级别/质量参数，因此也不导出调优常量。当前固定发布物在 native checked 边界将损坏/截断报告为 IOError，内存失败为 MemoryError；不能只依据包装层 fallback 声称必为 CompressionError。本轮只更正文档事实，不修改异常分派。

教学范例

完整源文件：examples/extlibs/snappy.xl

1. 一次性 + 流式

以下保留真实顶层流对象写法。JIT 可运行；独立程序仍受 M2 退役问题阻断，不能只根据正文正确就签收 AOT。

snappy.xl
import snappy

Buffer packed = snappy.compress("xlang snappy")
assert snappy.decompressText(packed) == "xlang snappy"
println("引擎版本: ", snappy.version())

auto encoder = snappy.compressor()
Buffer streamPacked = Buffer()
encoder.update("hello ")
streamPacked.append(encoder.drain())
encoder.update("stream")
streamPacked.append(encoder.drain())
encoder.finish()
streamPacked.append(encoder.drain())

auto decoder = snappy.decompressor()
decoder.update(streamPacked)
decoder.finish()
assert decoder.drain().text() == "hello stream"

2. 高冗余数据压缩率

压缩率
import snappy

Buffer redundant = Buffer()
int i = 0
while i < 256
    redundant.append("snappy-snappy-")
    i = i + 1
end
Buffer packed = snappy.compress(redundant)
println(redundant.len(), " -> ", packed.len(), " 字节")
assert packed.len() < redundant.len()
assert snappy.decompress(packed) == redundant

3. 双语串联记录

extlibs/snappy/examples/framed_records.xl 与 framed_records_c.c 读取同一条 59 字节标准流，逐字节 update/drain，跨过两种空块和第二个 identifier，完整结果为 abcabc、members=2、bytes=6。输入与结果所有权、运行命令和清理责任见包内 examples/README.md。教学收集有追加复制，不冒称零复制或吞吐基准。

4. 双语文件事务

extlibs/snappy/examples/file_transaction.xl 与 file_transaction_c.c 使用 UTF-8 文件名，在取消/业务回调失败时保护旧目标，然后立即重试恢复正文。五条执行路径与三行黄金输出一致，独占目录由例子清理；不将普通回调通过代替双故障OOM验收。

运行范例

终端（仓库根目录）
release\xl.exe run release\examples\extlibs\snappy.xl
release\xl.exe run release\extlibs\snappy\examples\basic.c

测试覆盖

2026-10-31：新增IO四路径×七类别、两种真实Writer扩容OOM、错误位置/身份/关闭归属/七项内存快照及立即恢复；两平台旧32断言失败→0。打开态96组全过，关闭态16组Windows仍两组残留；Linux同例过，但M2继续开放。各17条普通独立程序路径与旧格式/ABI/独立oracle通过。完整证据见包内 docs/io-file-audit-2026-10-31.md，旧日期数字不覆盖当前新增边界。

2026-10-30：原 C/XLang、进度、文件及内存边界保留。新增 test/empty_chunks_c.c 覆盖全部二分切点/前段 drain、流包装、CRC/畸形/截断拒绝、输入/输出/item/成员限额、真实 OOM 和立即恢复；Windows/Linux 均 379 场景零失败，Linux 含 ASan/UBSan/泄漏。abi_surface.xl 使用两种 update 和所有计数 getter，实际 26 个生成原型与 C 头一致；错误返回类型负例确实被拒绝。

独立 python-snappy 0.7.3 / cramjam 2.14.0 两平台验证原四载荷双向互通及新增八组空块流；Python/wheels 仅用于测试，不进入发布运行依赖。两平台各 13 条正常独立程序路径通过，最后顶层 M2 仍红；不能将 68/69 阶段符合要求称为完整包通过。输入/工具指纹、原始退出码和失败现场均保留，详包内 docs/empty-chunks-audit-2026-10-30.md。32 位、TSan、长期压力及全部文件事务故障仍未签收。

test/test_allocations.c 和 test/allocations.xl 验证 XRT 分配失败时的空结果、释放平衡、恢复和语言层 MemoryError 分类；不覆盖上游 Snappy 内部 allocator。

一次性二进制往返（含 NUL / 0xFF）
流式往返 + members 计数
分块收集 + inputBytes 计数器 + finished
高冗余数据压缩后显著更小
串联多成员流
损坏数据拒绝，当前 native checked 路径为 IOError
文件级往返 + overwrite 拒绝
文件进度回调、取消清理及限额失败时的既有目标保护
可选 Python Snappy 0.7.3 双向 framed 互通：二进制、重复数据及跨 64 KiB 分块

运行测试

终端（仓库根目录）
powershell -NoProfile -ExecutionPolicy Bypass -File release/extlibs/snappy/test/check.ps1
bash release/extlibs/snappy/test/check.sh

← 返回扩展库列表