murmur3

非加密哈希

MurmurHash3 x86_32 与 x64_128，用于非对抗性散列和既有格式互操作。不用于密码、签名、认证或防恶意碰撞。

公开函数

函数	参数与结果
`version()`	引擎版本 3.0.0；包版本另由清单记录为 1.0.0。
`hash32(data, seed=0)`	string 或 Buffer，返回 0..4294967295 的 int，不是有符号 32 位结果。
`hash32Hex(data, seed=0)`	同样输入，返回 4 字节小端摘要的 8 个小写 hex 字符。
`hash32Bytes(data, seed=0)`	返回同样的小端 4 字节 Buffer。
`hash128Hex(data, seed=0)`	x64_128，不是 x86_128；返回 32 个小写 hex 字符。
`hash128Bytes(data, seed=0)`	返回 x64_128 的小端 16 字节 Buffer。
`hashFile32(path, seed=0, maxInput=268435456, onProgress=null)`	文件的 x86_32 数值摘要。
`hashFile128Hex(path, seed=0, maxInput=268435456, onProgress=null)`	文件的 x64_128 文本摘要。
`hasher(seed=0, maxInput=268435456)`	创建 Murmur3Hasher，增量算法为 x64_128。

seed 必须在 0..4294967295，maxInput 必须大于零。文本按 UTF-8 字节处理，空输入合法；包含 NUL 的数据使用 Buffer。32 位 hex 表示摘要字节，不是数值的通常书写顺序，例如 abc 的 hash32 为 3017643002，hash32Hex 为 fa93ddb3。

流式快照与克隆

import murmur3

auto h = murmur3.hasher(seed = 42)
h.update("a")
h.update("bc")
assert h.digestHex() == "d6f7cfb39f08850d303d35422b711075"
auto branch = h.clone()
branch.update("!")
assert h.inputBytes == uint64(3)
h.reset()

update(string|Buffer) 追加数据；digestHex() 和 digestBytes() 是非终结快照，可以反复读取并继续追加。 clone 创建独立状态；reset 清空输入和失败状态，保留 seed 和预算。 inputBytes 为 uint64，valid 仅表示句柄非空。失败的 update 不部分接收数据，后续摘要与克隆也失败，必须先 reset。独立对象可并发，同一可变对象需串行访问。

文件、进度与取消

string digest = murmur3.hashFile128Hex("data.bin",
    onProgress = func(int current, int total, int output) as bool
        return true
    end)

每块最多读取 64 KiB，EOF 另通知一次，空文件也通知；最后计数可能重复。 current/total 为已读字节/总长度，未知总长为零，output 恒为零。 XRT 的 uint64 计数转公开 int 前检查范围。返回 false 抛 CancelledError， EOF 通知同样可以取消；回调异常保留类别与消息，允许嵌套独立操作。

无效参数为 ValueError，预算或表示范围超限为 RangeError，分配失败为 MemoryError；文件失败保留 XRT 错误分类。路径使用 XRT UTF-8 文件 API，失败不交付部分摘要。输入预算不是超时机制，读取也不承诺并发修改文件时的快照一致性。

C API 与所有权

include/xrt_murmur3.h 提供 Hash32/Hash128、OptionsInit/ErrorInit、 HasherCreate/Update/Digest/Clone/Reset/InputBytes/Error/Destroy 和 File32/File128。 C 核心独立于 xlang；已有 XRT 宿主只使用一份运行库。数值摘要零也是有效结果， C 端应读取 XRT 错误或显式错误记录，不把零当成通用失败标记。

文件核心借用 Reader，从当前游标读取，不销毁或回退它；最终回调成功后才提交摘要。已知剩余长度可预检，未知长度按块检查预算。进度帧包含 uint64 计数与 FINAL/TOTAL_KNOWN 标志。 C 核心零预算代表无业务上限，仍检查累计溢出。

include/murmur3_native.h 给出精确薄绑定 ABI。 hex 文本借用 XRT 临时区，清理或回退后失效，后续正常调用不会覆盖此前文本。返回的 xbuffer 归调用者所有，C 使用 xrtBufferDestroy，xlang 由 Buffer 接管。 adopt 只转移真实句柄的所有权，不允许伪造任意指针。

双语范例与验证范围

examples/extlibs/murmur3_basic.xl 与 extlibs/murmur3/examples/basic.c 展示文本、二进制、种子、流式与克隆。 examples/extlibs/murmur3.xl 与 extlibs/murmur3/examples/files.c 展示中文路径、文件进度、取消、回调异常和预算；两组分别与固定预期输出对照。

tools/check_extlib_murmur3.ps1 验证 576 组独立参考答案、8 种地址偏移、 23 个生成原型、UTF-8/Buffer、状态与 Reader 边界、回调、分配故障、四线程独立对象及 C/xlang JIT/AOT/GCC。 tools/check_extlib_murmur3.sh 验证 Linux 独立 C ASan/UBSan/泄漏边界及范例输出。测试记录输入哈希，不代表 Linux xlang、大端、32 位/ARM、共享可变对象或吞吐性能已验收。