1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
//! wordval-actor。
//!
//! 高性能单机内存 Actor 框架:
//!
//! | 场景 | 机制 |
//! |---|---|
//! | 遥测上行(100–1000Hz/机) | [`MailboxPolicy::LossTolerant`] 数据端口:单槽 latest-value-wins,内存 O(1) 与帧率解耦 |
//! | 指令下行(不可丢、要 ACK) | 有界控制通道背压 + [`ActorRef::ask`](关联应答 + 超时) |
//! | 失控保护(链路丢失 → 返航) | [`ActorContext::watchdog`] 一等滑动看门狗 + 控制面偏向(永不被遥测饿死) |
//! | 多机集群 HUD | [`Topic`] 广播扇出 + [`SnapshotTopic`] 零拷贝快照拉取 |
//! | 整机可靠性 | [`RestartPolicy`] 监督重启/指数退避 + [`ActorContext::watch`] 死亡通知 |
//!
//! # 快速上手
//!
//! ```
//! use wordval_actor::{Actor, ActorAction, ActorContext, ActorSystem, MailboxPolicy};
//!
//! struct Counter(u64);
//!
//! impl Actor for Counter {
//! type Message = u64;
//! const POLICY: MailboxPolicy = MailboxPolicy::Reliable { capacity: 64 };
//!
//! async fn handle(&mut self, n: u64, _ctx: &mut ActorContext<u64>) -> ActorAction {
//! self.0 += n;
//! ActorAction::Continue
//! }
//! }
//!
//! # async fn run() {
//! let system = ActorSystem::new();
//! let counter = system.spawn_named("counter", Counter(0)).unwrap();
//! counter.send(7).await.unwrap();
//! counter.try_send(3).unwrap();
//! # system.shutdown().await;
//! # }
//! ```
//!
//! ## 自调用约束(在 Actor 内部调用系统 API)
//!
//! 凡需等待目标 Actor 事件循环推进的 API —— [`ActorRef::ask`] /
//! [`ask_send`](ActorRef::ask_send) / [`ActorSystem::stop_and_wait`] /
//! [`stop_and_wait_timeout`](ActorSystem::stop_and_wait_timeout) —— 在目标
//! Actor 自身的 `handle` 内对自身调用会**立即 panic**(自调用防护:这类
//! 调用必然死锁或等满超时)。Actor 内部请求自身停止请用
//! [`ActorContext::stop`] 并返回 [`ActorAction::Stop`]。
//!
//! [`ActorSystem::shutdown`] 是唯一例外:在 Actor 内调用被支持 —— 调用者
//! 自身被排除出等待集(不白等宽限期、不被误判超时强制注销),其余 Actor
//! 照常等待;调用者在 `handle` 返回后优雅退出。
//!
//! 以上识别基于世代任务的 task-local 标记,**不跨 `tokio::spawn` 继承**:
//! 把调用转手给派生任务的写法不受防护,需自行避免。
//!
//! ## 链路会话:收原始帧 → 解码 → 写数据端口
//!
//! 解码任务(非 Actor)以任意速率覆盖写遥测帧;`LinkSession`
//! 事件循环永远只消费最新帧,积压不会膨胀:
//!
//! ```
//! use wordval_actor::{Actor, ActorAction, ActorContext, ActorError, ActorSystem, MailboxPolicy};
//!
//! struct LinkSession;
//! #[derive(Default)]
//! struct TelemetryFrame { attitude: [f32; 4] }
//!
//! impl Actor for LinkSession {
//! type Message = TelemetryFrame;
//! const POLICY: MailboxPolicy = MailboxPolicy::LossTolerant { capacity: 32 };
//!
//! async fn handle(&mut self, frame: TelemetryFrame, _ctx: &mut ActorContext<TelemetryFrame>) -> ActorAction {
//! let _ = frame; // 实际为覆盖写入 VehicleState 的数据端口
//! ActorAction::Continue
//! }
//! }
//!
//! # async fn read_modem() -> Vec<u8> { Vec::new() }
//! # fn decode(raw: Vec<u8>) -> TelemetryFrame { let _ = raw; TelemetryFrame::default() }
//! # fn demo(system: ActorSystem) -> Result<(), ActorError> {
//! let session = system.spawn_named("link-uav1", LinkSession)?;
//! let mut writer = session.data_port().unwrap(); // 交给解码任务
//! tokio::spawn(async move {
//! loop {
//! let raw = read_modem().await;
//! writer.send(decode(raw)); // 覆盖式,永不阻塞
//! }
//! });
//! # Ok(())
//! # }
//! ```
//!
//! ## 机体状态机:心跳看门狗 → 超时自动返航
//!
//! ```
//! use wordval_actor::{Actor, ActorAction, ActorContext};
//! use std::time::Duration;
//!
//! struct VehicleState;
//! struct Telemetry;
//! enum VehicleMsg { Telemetry(Telemetry), LinkLost }
//!
//! impl Actor for VehicleState {
//! type Message = VehicleMsg;
//!
//! async fn handle(&mut self, msg: VehicleMsg, ctx: &mut ActorContext<VehicleMsg>) -> ActorAction {
//! match msg {
//! VehicleMsg::Telemetry(t) => {
//! // 每帧一行滑动重置 3s 看门狗:首次帧自动武装,
//! // 触发后再次调用自动再武装,无需业务侧管理句柄
//! ctx.watchdog(Duration::from_secs(3), VehicleMsg::LinkLost);
//! self.apply(t);
//! }
//! VehicleMsg::LinkLost => {
//! self.failsafe_rtl(); // 失控保护:发送返航指令
//! }
//! }
//! ActorAction::Continue
//! }
//! }
//! # impl VehicleState {
//! # fn apply(&mut self, _t: Telemetry) {}
//! # fn failsafe_rtl(&mut self) {}
//! # }
//! ```
//!
//! 看门狗度量**处理节奏**而非到达节奏:喂狗在 `handle` 内,`timeout`
//! 内没有任何消息处理到喂狗点即触发(邮箱积压、慢处理、调度停顿都
//! 算数)——阈值得按最坏处理时延选取;监督重启的新世代不自动武装,
//! 保护自首帧喂狗起恢复。详见 [`ActorContext::watchdog`]。
//!
//! ## 机队监督:watch 全部机体,接收终止告警
//!
//! ```
//! use wordval_actor::{Actor, ActorAction, ActorContext, ActorSignal, SpawnOptions};
//!
//! struct FleetSupervisor;
//! struct FleetMsg;
//!
//! impl Actor for FleetSupervisor {
//! type Message = FleetMsg;
//!
//! async fn handle(&mut self, _msg: FleetMsg, _ctx: &mut ActorContext<FleetMsg>) -> ActorAction {
//! ActorAction::Continue
//! }
//!
//! async fn on_signal(&mut self, sig: ActorSignal, _ctx: &mut ActorContext<FleetMsg>) -> ActorAction {
//! if let ActorSignal::Terminated(t) = sig {
//! tracing::info!("机体 {:?} 已终止,原因 {}", t.name, t.cause);
//! }
//! ActorAction::Continue
//! }
//! }
//!
//! let opts = SpawnOptions::named("fleet");
//! // spawn 后在 on_start 中逐个 ctx.watch(vehicle_ref)
//! # let _ = opts;
//! ```
//! ## Cargo 特性
//!
//! - `wordval-plugin`(默认开启):wordval 插件系统集成
//! (`ActorPlugin` / `actor_system` / `try_actor_system`),
//! 会引入 `wordval-core` 依赖。独立使用本 crate 时可
//! `default-features = false` 裁掉该集成及其依赖子图。
pub use ;
pub use ;
pub use ActorContext;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;