Automerge-C 中 AMsave 和 AMload 操作后 Map 值异常问题解析

问题现象

在使用 Automerge-C 库时，开发者遇到了一个奇怪的现象：在对文档进行 AMsave 保存和 AMload 加载操作后，Map 中的值有时会变为零。具体表现为：

1. 在循环中反复保存和加载文档后，Map 中的浮点数值会意外变为零
2. 有时还会出现访问冲突异常，程序崩溃
3. 问题通常在几次循环迭代后出现

根本原因分析

经过深入分析，发现问题的根源在于 Automerge-C 的 API 使用方式存在两个关键错误：

1. 对象 ID 生命周期管理不当

在 Automerge-C 中，AMobjId 结构体指针实际上是指向 AMresult 结构体内部的数据。当开发者过早释放了包含这些对象 ID 的 AMresult 结构体后，继续使用这些对象 ID 就会导致未定义行为，包括：

• 访问冲突异常（当内存被回收后）
• 数据读取错误（当内存被重用后）

2. 内存泄漏风险

在错误处理路径中，存在 AMresult 结构体未被正确释放的情况，这会导致内存泄漏问题。

正确使用模式

要正确使用 Automerge-C 的 API，特别是涉及对象 ID 时，需要注意以下几点：

1. 保持结果对象生命周期

必须确保 AMresult 结构体的生命周期覆盖所有对其内部数据的访问。对于对象 ID (AMobjId)，在不再需要前不能释放其所属的结果对象。

2. 使用 AMstack 管理资源

Automerge-C 提供了 AMstack 工具来简化资源管理。通过创建局部栈并在适当的作用域结束时释放，可以确保资源的正确生命周期：

{
    AMstack *stack;
    // 操作代码...
    AMstackFree(&stack);
}

3. 多值类型检查

对于可能返回多种类型值的函数（如 AMcommit），可以使用位掩码来检查多种可能的返回类型：

AMstackItem(NULL, AMcommit(doc, AMstr("Update state"), NULL), 
           abort_cb, AMexpect(AM_VAL_TYPE_CHANGE_HASH | AM_VAL_TYPE_VOID));

最佳实践建议

1. 作用域管理：为每个逻辑块创建单独的 AMstack，确保资源在正确的时间释放

2. 错误处理：始终检查 API 调用的返回状态，并在错误路径上正确释放资源

3. 类型安全：使用 AMexpect 宏验证返回值的类型，避免类型不匹配错误

4. 文档参考：建议开发者构建本地 Automerge-C 文档，以便随时查阅 API 的详细行为说明

总结

Automerge-C 是一个功能强大的 CRDT 实现库，但其 C API 需要开发者特别注意资源生命周期管理。通过正确使用 AMstack 工具和遵循对象生命周期规则，可以避免这类数据损坏和程序崩溃问题。理解这些底层机制对于构建稳定可靠的协同编辑应用至关重要。