2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)

基线核心宗旨：“Type-Safe & Traceable (类型安全与可追溯)”。内部控制事件不跨越进程边界（不涉及 Protobuf 序列化），它们是纯粹的 C++ 运行时对象。设计重心在于利用 C++ 类型系统防止误用，并强制携带全链路追踪上下文。

1. 核心设计契约 (Design Contracts)

强制继承 (Mandatory Inheritance)：
- 所有在 EventBus 上流转的事件必须继承自 BaseEvent。
- 理由：确保所有事件天然携带 TraceID 和 Timestamp，实现无死角的审计与追踪。
轻量级负载 (Lightweight Payload)：
- 禁止：在事件对象中直接嵌入大块内存（如 vector<float> 原始波形数据）。
- 允许：状态码、配置参数、资源句柄（智能指针）、元数据摘要。
- 理由：控制平面应保持低延迟。大块数据应通过数据面（DataQueue）流转，控制面仅传递“指向数据的指针”或“操作指令”。
值语义与移动优化 (Value Semantics & Move Semantics)：
- 事件对象默认按值传递（Copy/Move）。
- 必须支持移动构造（Move Constructor），以便高效地在 EventBus 的异步队列中转移。

2. 根模式定义 (Root Schema)

这是所有控制信令的“父类契约”。

/**
 * @brief 所有内部控制事件的基类
 * @note 即使是空事件，大小也至少为 16 字节 (TraceID + Timestamp)
 */
struct BaseEvent {
    // --- 上下文核心 (Context Core) ---
    
    // 全链路追踪 ID (从 TraceContext 自动捕获或继承)
    uint64_t trace_id;
    
    // 事件生成时的精确时间 (UTC Microseconds)
    // 用于计算控制指令在队列中的排队延迟 (Queueing Latency)
    uint64_t timestamp_us;

    // --- 构造基线 ---
    BaseEvent() {
        // 自动注入上下文，确保业务代码无需手动填写
        trace_id = TraceContext::getCurrentId(); 
        timestamp_us = Clock::nowInUs();
    }
    
    virtual ~BaseEvent() = default; // 允许作为基类指针传递（如果需要统一日志处理）
};

3. 核心事件分类定义 (Concrete Schemas)

基于 2.3 章节 确立的各个控制子系统，我们定义以下四类核心事件。

3.1 生命周期与编排类 (Lifecycle & Orchestration)

服务于 2.3.3 和 2.3.4。这类事件对可靠性要求最高。

// 指令：启动模块
struct StartModuleEvent : public BaseEvent {
    std::string target_module; // 目标模块名
    // 可选：携带启动参数或配置覆盖
    // std::map<string, string> overrides; 
};

// 回执：模块运行中
struct ModuleRunningEvent : public BaseEvent {
    std::string module_name;
};

// 告警：模块故障 (Rich Context from 2.3.4)
struct ModuleFailedEvent : public BaseEvent {
    std::string module_name;
    ErrorCode error_code;      // 标准化错误码
    bool is_hardware_fault;    // 是否硬件故障 (决定是否熔断)
    std::string debug_info;    // 现场快照 (堆栈、显存状态等)
};

3.2 资源保护与仲裁类 (Resource & Safety)

服务于 2.3.5。这类事件对响应速度要求最高。

// 告警：系统过载 (由监控模块发出)
struct SystemOverloadEvent : public BaseEvent {
    enum class Type { THERMAL, POWER, MEMORY };
    enum class Level { WARNING, CRITICAL };
    
    Type type;
    Level level;
    float current_value; // e.g., 95.5 (Celsius)
};

// 指令：执行节流 (由调度器发出)
struct SetComputeThrottleEvent : public BaseEvent {
    enum class Level { NO_THROTTLE, LIGHT, HEAVY, SUSPEND };
    Level level;
    // 接收方收到后，需立即调整 sleep 策略或丢包策略
};

3.3 配置热更新类 (Configuration Transaction)

服务于 2.3.6。这类事件需要承载复杂负载（配置数据）。

// 事务：配置变更补丁
// 采用 RCU 模式，负载通过 shared_ptr 传递，避免深拷贝
struct ValidateConfigEvent : public BaseEvent {
    uint64_t config_version;
    // 使用智能指针传递复杂的配置树，确保事件本身轻量
    std::shared_ptr<const ConfigPatch> patch; 
};

// 提交：确认变更
struct CommitConfigEvent : public BaseEvent {
    uint64_t config_version; // 必须匹配 Validate 中的版本
};

3.4 性能遥测类 (Telemetry)

服务于 2.3.7。这类事件吞吐量最大，必须极致精简。

// 遥测：指标快照
struct MetricsUpdateEvent : public BaseEvent {
    // 使用扁平化 Map 传输快照
    // Key 命名规范: "metric_name{tag=val,…}"
    std::unordered_map<std::string, double> metrics;
    
    // 优化建议：
    // 如果 std::unordered_map 造成频繁 malloc，
    // 可考虑使用预分配的 vector<MetricPair> 或类似 SmallVector 的优化容器
};

4. 模式设计自检 (Design Checklist)

检查项	符合标准	设计意图
继承关系	✅ Yes	所有事件均继承自 `BaseEvent`，保证 TraceID 存在。
内存所有权	✅ Yes	复杂对象（如 ConfigPatch）使用 `shared_ptr` 传递，避免总线拷贝大对象。
类型安全	✅ Yes	避免使用 `void*` 或 `EventId` 整数流，利用 C++ 类型系统进行分发。
序列化无关	✅ Yes	结构体中包含 `std::string` 等非 POD 类型，明确不直接用于网络传输（需经由 2.5.3 转换）。

总结： 2.5.2 确立了控制平面的“通用语言”。这套定义确保了控制指令在进程内传输时：

可追踪（自带 TraceID）。
低延迟（避免大内存拷贝）。
强类型（编译期检查错误）。

这为 2.3 节定义的所有控制逻辑提供了坚实的数据结构支撑。

6.1 KiB Raw Blame History Unescape Escape