178 lines
6.1 KiB
Markdown
178 lines
6.1 KiB
Markdown
---
|
||
tags: []
|
||
aliases:
|
||
- 2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)
|
||
date created: 星期一, 十一月 24日 2025, 10:39:09 晚上
|
||
date modified: 星期一, 十一月 24日 2025, 10:56:20 晚上
|
||
---
|
||
|
||
# 2.5.2 内部控制事件模式定义 (Internal Control Event Schema Definition)
|
||
|
||
**基线核心宗旨**：**“Type-Safe & Traceable (类型安全与可追溯)”**。
|
||
内部控制事件不跨越进程边界（不涉及 Protobuf 序列化），它们是纯粹的 C++ 运行时对象。设计重心在于利用 C++ 类型系统防止误用，并强制携带全链路追踪上下文。
|
||
|
||
-----
|
||
|
||
## 1\. 核心设计契约 (Design Contracts)
|
||
|
||
1. **强制继承 (Mandatory Inheritance)**：
|
||
|
||
- 所有在 `EventBus` 上流转的事件 **必须** 继承自 `BaseEvent`。
|
||
- **理由**：确保所有事件天然携带 `TraceID` 和 `Timestamp`，实现无死角的审计与追踪。
|
||
|
||
2. **轻量级负载 (Lightweight Payload)**：
|
||
|
||
- **禁止**：在事件对象中直接嵌入大块内存（如 `vector<float>` 原始波形数据）。
|
||
- **允许**：状态码、配置参数、资源句柄（智能指针）、元数据摘要。
|
||
- **理由**：控制平面应保持低延迟。大块数据应通过数据面（DataQueue）流转，控制面仅传递“指向数据的指针”或“操作指令”。
|
||
|
||
3. **值语义与移动优化 (Value Semantics & Move Semantics)**：
|
||
|
||
- 事件对象默认按**值传递**（Copy/Move）。
|
||
- 必须支持移动构造（Move Constructor），以便高效地在 `EventBus` 的异步队列中转移。
|
||
|
||
-----
|
||
|
||
## 2\. 根模式定义 (Root Schema)
|
||
|
||
这是所有控制信令的“父类契约”。
|
||
|
||
```cpp
|
||
/**
|
||
* @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**。这类事件对**可靠性**要求最高。
|
||
|
||
```cpp
|
||
// 指令：启动模块
|
||
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**。这类事件对**响应速度**要求最高。
|
||
|
||
```cpp
|
||
// 告警：系统过载 (由监控模块发出)
|
||
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**。这类事件需要承载**复杂负载**（配置数据）。
|
||
|
||
```cpp
|
||
// 事务：配置变更补丁
|
||
// 采用 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**。这类事件**吞吐量最大**，必须极致精简。
|
||
|
||
```cpp
|
||
// 遥测：指标快照
|
||
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** 确立了控制平面的“通用语言”。这套定义确保了控制指令在进程内传输时：
|
||
|
||
1. **可追踪**（自带 TraceID）。
|
||
2. **低延迟**（避免大内存拷贝）。
|
||
3. **强类型**（编译期检查错误）。
|
||
|
||
这为 2.3 节定义的所有控制逻辑提供了坚实的数据结构支撑。
|