C/C++ API 使用规范

C++17 项目优先包含 revo3/revo3.hpp，使用 revo3::Manager、revo3::Hand 和 RAII。纯 C 与其他语言绑定使用 revo3-sdk.h。头文件、动态库和 API 文档必须来自同一份正式 C/C++ SDK 发布包。

C++ 生命周期与所有权

• Manager 和 Hand 是 move-only 对象，不要复制句柄；移动后不得继续使用源对象。
• 优先依靠作用域和 RAII 释放资源；需要提前结束连接时可显式调用 close()。
• 订阅、MotionHandle 和 ServoSession 具有独立生命周期，应在持有它们的对象析构前结束或关闭。
• 断线后关闭旧对象并重新连接。旧连接创建的运动句柄、订阅和会话不得复用。
• 让对象的生命周期顺序与所有权关系一致，避免后台回调访问已经析构的应用状态。

基础 RAII 结构见 quickstart.cpp，多设备管理见 multi_hand.cpp。

超时、错误与恢复

• 使用 std::chrono 表达持续时间和超时，不使用无单位的魔法数字。
• MotionHandle 返回不代表运动已经完成；等待时设置有限超时，并处理取消和非完成状态。
• 捕获 revo3::SdkError，记录错误码、操作效果和恢复要求，不要只依据 what() 文本决定重试。
• 超时或 Indeterminate 结果下，先读取 State 和 Health 确认设备状态，再决定是否重复写操作。
• 重连后重新获取设备信息和关节布局，并重新执行健康预检。

运动和超时示例见 mit_plan.cpp，错误恢复原则见错误处理与恢复。

并发与实时控制

• 为每只手指定唯一的运动控制所有者，不并发混用离散运动、Servo、示教和回放。
• 高频目标通过 ServoSession 发送，并明确发送节拍、命令超时和退出清理流程。
• 订阅回调或数据处理路径中不要执行长时间阻塞任务；耗时处理应转移到应用自己的有界队列或工作线程。
• 共享应用状态时使用适当的同步机制，并在关闭订阅或会话后再析构回调所依赖的对象。
• 不假定应用线程调度频率等于总线速率或固件采样率。

连续控制见 streaming_control.cpp，订阅处理见 subscriptions.cpp。

C ABI 资源与回调

• 每个创建函数都必须匹配对应的释放函数；为所有成功和失败路径定义统一清理出口。
• 回调中的临时指针只能在头文件声明的生命周期内使用；异步保存或跨线程传递前复制所需字段。
• 先注销或关闭回调来源，再释放回调上下文，避免回调访问悬空指针。
• C 结构体布局、字符串、数组和错误对象的所有权以 SDK 头文件注释为准。
• 检查所有返回状态，公共符号使用 revo3_ 前缀；不要混用不同版本的 Header 与动态库。

设备发现和完整清理流程可参考 discover_devices.cpp。