📚 课程目录第4章属性存储与获取

4. 属性存储与获取：getProperty() 接口、setProperty() 接口、同步与异步调用机制

Vehicle HAL 的属性存储与获取是车载系统与上层应用交互的核心通道。本章深入剖析 getProperty() 与 setProperty() 接口的实现原理，并重点讲解同步与异步调用机制的设计差异与适用场景。

4.1 属性访问接口总览

Vehicle HAL 定义了两组核心接口用于属性的读写操作。下表对比了 getProperty() 与 setProperty() 的基本特征：

接口	方向	典型触发源	返回值特征	错误处理
getProperty()	读取	应用层、服务层	立即返回属性值或错误码	属性不存在 / 权限不足 / 超时
setProperty()	写入	应用层、策略引擎	返回操作状态（成功/失败/异步进行中）	值无效 / 写入冲突 / 硬件故障

4.2 getProperty() 接口实现

getProperty() 接口负责从 Vehicle HAL 的属性存储区读取指定属性的当前值。其实现流程包含以下关键步骤：

参数校验：检查 prop_id 是否在已注册属性列表中，验证 area_id 合法性。
权限检查：确认调用方具有该属性的读取权限。
缓存查询：优先从内存缓存中获取属性值，减少硬件访问延迟。
硬件读取：若缓存缺失或标记为“强制刷新”，则通过底层驱动读取物理值。
值封装：将原始数据转换为 VehiclePropValue 结构体返回。

  关键设计点： 对于高频读取的属性（如车速、转速），建议启用缓存策略，避免每次调用都穿透到硬件层，降低系统负载。

4.3 setProperty() 接口实现

setProperty() 接口用于向 Vehicle HAL 写入属性值。其实现需特别注意写入安全与状态同步：

值验证：检查写入值是否在属性定义的合法范围内，包括数据类型、数值上下限。
写入仲裁：处理多个客户端同时写入同一属性的冲突，通常采用“最后写入者胜出”或“优先级仲裁”策略。
硬件写入：将验证通过的值下发到硬件抽象层，触发实际物理操作。
回调通知：写入完成后，通过属性变化回调机制通知订阅方。

注意： 对于关键安全属性（如刹车、转向），setProperty() 必须实现写入确认机制，确保硬件端成功执行后才返回成功状态。

4.4 同步调用机制

同步调用是 Vehicle HAL 中最直接的调用模式。调用方发起请求后，线程阻塞等待结果返回。

同步调用特点：

调用方线程挂起，直到 HAL 返回结果或超时。
适用于低延迟、确定性高的属性操作（如读取本地缓存属性）。
实现简单，无需复杂的状态机管理。
缺点：长时间阻塞会拖慢调用方线程，不适合耗时操作。

典型同步调用代码结构：

// 同步 getProperty 示例
VehiclePropValue propValue;
StatusCode status = hal->getProperty(propId, areaId, &propValue, timeout_ms);
if (status == StatusCode::OK) {
    // 使用 propValue
} else {
    // 处理错误
}

4.5 异步调用机制

异步调用机制允许调用方发起请求后立即返回，不阻塞当前线程。结果通过回调函数或 Future/Promise 机制传递。

异步调用特点：

调用方线程不被阻塞，可继续处理其他任务。
适用于高延迟操作（如硬件初始化、固件升级）。
需要管理回调上下文，防止回调泄漏或重复触发。
实现复杂度较高，需设计超时与取消机制。

典型异步调用代码结构：

// 异步 setProperty 示例
hal->setPropertyAsync(propId, areaId, propValue,
    [](StatusCode status, int32_t cookie) {
        if (status == StatusCode::OK) {
            // 写入成功处理
        } else {
            // 写入失败处理
        }
    }, cookie);

4.6 同步 vs 异步调用对比

对比维度	同步调用	异步调用
线程阻塞	是，调用方线程挂起	否，调用方立即返回
适用场景	低延迟、确定性操作	高延迟、不确定时长操作
实现复杂度	低	高（需管理回调/状态机）
资源消耗	占用调用线程资源	需额外回调上下文存储
超时处理	调用方设置超时参数	需独立超时定时器
典型属性示例	车速、转速、车门状态	固件升级、诊断请求、校准

4.7 同步与异步调用流程架构

下图展示了 Vehicle HAL 中同步与异步调用的完整数据流路径：

4.8 属性存储与获取的最佳实践

实践建议：

对于读取频率 > 10Hz 的属性，优先使用同步调用 + 缓存策略，减少异步回调开销。
对于写入后需要确认硬件状态的属性，使用异步调用 + 超时重试机制，避免调用方长时间阻塞。
在属性存储层实现读写锁分离，支持并发读取与串行写入，提升系统吞吐量。
为每个属性配置独立的超时阈值，避免统一超时导致误判。

4.9 属性存储与获取的异常处理

在实际车载系统中，属性访问可能遇到多种异常情况。下表总结了常见异常及其处理策略：

异常类型	触发条件	推荐处理方式
属性未注册	prop_id 不在 HAL 属性列表中	返回 StatusCode::NOT_AVAILABLE，记录错误日志
权限不足	调用方无读写权限	返回 StatusCode::ACCESS_DENIED，触发安全审计
硬件故障	底层驱动返回错误	返回 StatusCode::INTERNAL_ERROR，尝试恢复或降级
超时	操作超过预设时间	返回 StatusCode::TIMEOUT，取消当前操作
值无效	写入值超出合法范围	返回 StatusCode::INVALID_ARG，提示调用方修正

通过合理设计同步与异步调用机制，结合完善的异常处理策略，Vehicle HAL 的属性存储与获取模块能够为上层应用提供高效、可靠的车辆数据访问服务。