xxhash

非密码哈希

2026-10-29 全局哈希器检查确认 M2 主线阻断：Windows/Linux JIT 退出0；独立 EXE 均打印校验 PASS 后在退出期报状态错误、退出1。默认门禁已接入并保留失败现场，旧向量、线程和局部对象通过不覆盖该边界，暂不作完整发布签收；不提前销毁或移动全局对象绕开。

XXH32、XXH64 与 XXH3，面向数据分布、去重与快速指纹。内嵌 C 后端，不需要额外 xxHash DLL；不用于口令、签名或防恶意篡改。

函数

函数	参数与返回
`version()`	返回固定后端版本 0.8.3。
`hash32(data, seed=0)`	Buffer 或 string，种子 uint32，返回 uint32。
`hash64(data, seed=0)`	Buffer 或 string，种子 uint64，返回 uint64。
`hash32Hex / hash64Hex`	相同输入，分别返回 8/16 个小写 hex 字符。
`hash3_64(data, seed=0)`	Buffer 或 string，一次性 XXH3-64，返回 uint64。
`hash3_64Hex / hash3_128Hex`	一次性 XXH3 摘要，返回 16/32 个小写 hex 字符；128 位结果高位在前。
`hashFile64(path, seed, maxInput, onProgress)`	返回 uint64；默认 seed=0、maxInput=268435456、onProgress=null。
`hashFile64Hex(...)`	相同参数，返回 16 个小写 hex 字符。
`hasher(seed=0, maxInput=268435456)`	返回 Xxhash64Hasher。

文本按 UTF-8 字节计算，不先复制为 Buffer。二进制 Buffer 可含零字节；空输入合法。整数摘要保留所有无符号位，负数种子和越界值不会隐式截断。XXH3 当前只有一次性接口，流式与文件接口仍为 XXH64。

增量对象

import xxhash

auto h = xxhash.hasher()
h.update("a")
h.update("bc")
assert h.digestHex() == "44bc2cf5ad770999"
assert h.digest() == xxhash.hash64("abc")
h.reset()

update(Buffer|string) 追加输入；digest() 和 digestHex() 是可重复读取的快照，之后仍可追加。inputBytes 是 uint64 字节计数， valid 只检查句柄非空。超限或非法 update 使状态失败，reset 清除输入和失败状态、保留种子与预算。不同对象可独立并发，同一可变对象须串行操作。

文件与回调

auto sum = xxhash.hashFile64("data.bin",
    onProgress = func(int current, int total, int output) as bool
        return true
    end)

每块最多 64 KiB，EOF 再通知一次，空文件也通知。参数为已读、总长、输出字节；未知总长为 0，输出恒为 0。末次计数可能重复。回调返回 false 抛 CancelledError，用户异常保留类别和消息，允许嵌套另一次文件哈希。

maxInput 必须为正；非法参数为 ValueError、超限为 RangeError、分配失败为 MemoryError。文件路径通过 XRT UTF-8 API 处理，内嵌 NUL 报 ValueError，打开失败沿用 FileError；不修改输入、不返回部分摘要。预算不代表 CPU 限制或并发写入下的文件快照。

C 与验证

include/xrt_xxhash.h 提供核心 xrtXxhash32/64、xrtXxhash3_64/128、OptionsInit/LimitsInit/ErrorInit、 HasherCreate/Update/Digest/Reset/InputBytes/Error/Destroy 和 File64。 File64 借用 Reader，从当前游标读取，成功才写输出，保留 C 进度帧的 FINAL/TOTAL_KNOWN 标志。

流对象用 xrtXxhashOptionsInit，文件接口的显式限额用 xrtXxhashLimitsInit；通用资源初始化会设置与哈希无关的非零限额。初始化后的零输入预算表示不设业务上限，仍检查溢出；配置的长度/版本必须匹配，除输入预算外的限额、标志和保留字段必须为零，错误配置在读取前拒绝。薄绑定的 maximum=0 表示默认预算。原生 ABI 头为 include/xxhash_native.h：hex 返回独立拥有的 char*，使用后以 xrtFree 释放，失败为 NULL 并设置 XRT 错误。结果不依赖 hasher 或创建线程的生命周期；版本号与错误消息仍为只读借用，不能释放。XLang 用 @owned string 直接接管文本，不再经临时区复制；接管仍需一次长度扫描。

双语范例：examples/extlibs/xxhash_basic.xl 和 extlibs/xxhash/examples/basic.c，对照同一固定输出；从仓库根目录可直接运行 release/xl.exe run release/extlibs/xxhash/examples/basic.c，无需额外源文件参数。完整教学见 examples/extlibs/xxhash.xl；其文件回调段使用独占系统临时目录并在异常路径清理，不写入固定的构建目录。

2026-09-27 的限定专项：37 项 Windows 检查、19 个生成原型、124 条独立向量，以及 Unicode、Reader/回调、分配故障、四线程、JIT/AOT 与双语固定输出对照。负数或超宽种子在语义阶段拒绝；TCC 的系统头包含顺序也有回归检查。入口为 tools/check_extlib_xxhash.ps1、tools/check_extlib_xxhash.sh 与 tools/check_extlib_linux_xl.sh xxhash。 2026-10-24 使用更新后的 Windows 发布版复验，默认门禁包含严格 C、独立向量、生成原型、双语输出及公开范例 AOT，全部通过；旧版共享缺符号阻断已解除。Linux 包门禁也通过 C ASan/UBSan、单文件直跑及 XLang JIT 对照。 -SkipAot 仅供开发时缩短反馈。XXH32 流式对象仍未公开，不宣称共享可变对象并发或性能已认证。

2026-10-26 当前 Windows 默认门禁 44 项检查、19 个生成原型与 C/XLang JIT/AOT 通过；Linux C ASan/UBSan、私有入口/种子负例、七条独立 EXE AOT 及双语范例输出对照通过。两平台短时 x64 路径已验，32 位/ARM、长时压力与性能基准仍未覆盖。

2026-10-27 增加一次性 XXH3-64/128：C 核心覆盖 0、1、3、16、17、240、241、4096 字节边界与多种种子；Windows/Linux 门禁通过 C 边界、分配故障、XLang JIT/AOT 及八行双语黄金输出。详情见包内 README。

2026-10-28 十条 hex 返回路径改为直接移交 XRT 文本分配。Windows/Linux 默认门禁通过逐入口生成 C 检查、分配故障与恢复、四线程结果隔离及线程退出后结果存活；Linux 另通过 C ASan/UBSan 和九份独立 XLang EXE。WSL 挂载盘的 AOT 超时另有对照记录，不将原生临时目录的通过外推为挂载盘性能已修复。

后端固定为 v0.8.3 commit e626a72bc2321cd320e953a0ccf1584cad60f363， BSD-2-Clause；来源、适配层和独立向量见包内 VENDOR.md。