actor_lite/async_actor.rs
1use crate::{ActorContext, ActorHandle, CancelToken, core::ActorCore};
2
3use tokio::sync::broadcast;
4use tracing::{trace, warn};
5/// actor 的**异步壳**。
6///
7/// 在 [`ActorCore`] 之上增加两件事:`run` 的签名(返回 future)和 [`spawn`](AsyncActor::spawn)。
8/// 相比只实现 `ActorCore`,适合"跑在 tokio 任务里、用 `.await` 等网络/定时器"的 actor。
9///
10/// # 要求
11///
12/// - `Self: Send + 'static`:整个 actor 会被搬进 tokio 任务。握着 `Rc<...>`、
13/// GPU 句柄这类 `!Send` 资源的 actor **不能**用它,请改用只要求 `ActorCore` 的方式,
14/// 或等线程壳;
15/// - [`spawn`](AsyncActor::spawn) 内部调用 `tokio::spawn`,**调用线程必须有 tokio runtime**。
16///
17/// # 定义一个 actor
18///
19/// 需要两段 `impl`:关联类型与初始化给 [`ActorCore`],`run` 给本 trait。
20///
21/// # 示例
22///
23/// ```no_run
24/// # use actor_lite::{ActorCore, AsyncActor, ActorContext};
25/// struct Counter {
26/// target: u32,
27/// }
28///
29/// impl ActorCore for Counter {
30/// type Cmd = ();
31/// type Event = u32;
32/// type State = u32;
33/// type Progress = f32;
34/// fn init_state_and_progress(&self) -> (Self::State, Self::Progress) {
35/// (0, 0.0)
36/// }
37/// }
38///
39/// impl AsyncActor for Counter {
40/// fn run(self, mut context: ActorContext<Self>) -> impl Future<Output = ()> + Send + 'static {
41/// async move {
42/// let mut count = 0u32;
43/// loop {
44/// if context.check_cmd().is_none() {
45/// // 没有命令时做自己的事
46/// }
47/// if count >= self.target {
48/// break;
49/// }
50/// count += 1;
51/// context.update_state(count);
52/// context.update_progress(count as f32 / self.target as f32);
53/// context.send_event(count);
54/// }
55/// }
56/// }
57/// }
58/// # let _ = Counter { target: 3 }.spawn();
59/// ```
60pub trait AsyncActor: ActorCore + Send + 'static {
61 /// 启动 actor:把 `run` 返回的 future 交给 `tokio::spawn`。
62 ///
63 /// 返回 actor 的控制端 [`ActorHandle`],外部通过它发送命令、读取状态/进度、订阅事件。
64 ///
65 /// # Panic
66 ///
67 /// 必须从 tokio runtime 上下文里调用,否则 panic(`there is no reactor running`)。
68 /// 另外 `run` 自己 panic 只会让这个任务死掉,handle 不会收到通知。
69 fn spawn(self) -> ActorHandle<Self> {
70 let (init_state, init_progress) = self.init_state_and_progress();
71 let (context, handle) = Self::channel(init_state, init_progress);
72 tokio::spawn(self.run(context));
73 trace!("spawn actor: {}", std::any::type_name::<Self>());
74 handle
75 }
76 /// actor 的主循环。
77 ///
78 /// 拿到后端的 [`ActorContext`] 后自己决定循环结构:收命令、干活、更新状态/进度、发事件。
79 /// 返回时 actor 结束,之后 handle 的 [`send_cmd`](ActorHandle::send_cmd) 会返回 `Err`。
80 ///
81 /// # 注意
82 ///
83 /// - 想让 [`ActorHandle::stop`] 生效,循环里必须监听取消信号
84 /// (`select!` 到 `ctx.cancel_clone().cancelled()`,或每轮 `is_cancelled()`);
85 /// - 所有 handle 都被 drop 后两件事同时发生:命令通道关闭、
86 /// [`wait_for_cmd`](ActorContext::wait_for_cmd) 返回 `None`。
87 ///
88 /// # 示例
89 ///
90 /// ```no_run
91 /// # use actor_lite::{ActorCore, AsyncActor, ActorHandle, ActorContext};
92 /// struct MyActor;
93 /// impl ActorCore for MyActor {
94 /// type Cmd = ();
95 /// type Event = ();
96 /// type State = ();
97 /// type Progress = ();
98 /// fn init_state_and_progress(&self) -> (Self::State, Self::Progress) {
99 /// ((), ())
100 /// }
101 /// }
102 /// impl AsyncActor for MyActor {
103 /// fn run(self, mut context: ActorContext<Self>) -> impl Future<Output = ()> + Send + 'static {
104 /// async move {
105 /// let cancel = context.cancel_clone();
106 /// loop {
107 /// tokio::select! {
108 /// _ = cancel.cancelled() => break,
109 /// cmd = context.wait_for_cmd() => {
110 /// if cmd.is_none() { break; } // 所有 handle 都没了
111 /// // ...处理命令
112 /// }
113 /// }
114 /// // 发送事件、更新进度和状态
115 /// context.send_event(());
116 /// context.update_progress(());
117 /// context.update_state(());
118 /// }
119 /// }
120 /// }
121 /// }
122 /// ```
123 fn run(self, context: ActorContext<Self>) -> impl Future<Output = ()> + Send + 'static;
124}
125impl<A: AsyncActor> ActorHandle<A> {
126 /// 异步监听状态变化。
127 ///
128 /// 每次状态变化时会调用 `op`,传入最新状态;返回的 [`CancelToken`] 调用
129 /// [`CancelToken::cancel`] 后停止监听。
130 ///
131 /// # 注意
132 ///
133 /// 内部使用 `tokio::spawn`,**调用线程必须有 tokio runtime**,否则会 panic
134 /// (`there is no reactor running`)。同步宿主(GUI 回调、GTK/iOS 主线程等)请改用
135 /// [`state_rx`](ActorHandle::state_rx) 拿 `watch::Receiver` 自己拉(每帧
136 /// `has_changed()`),或 [`get_state`](ActorHandle::get_state) 轮询,
137 /// 或基于 [`get_events_rx`](ActorHandle::get_events_rx) 每帧 `try_recv()`。
138 pub fn state_listen_async<F, Fut>(&self, mut op: F) -> CancelToken
139 where
140 F: FnMut(A::State) -> Fut + Send + 'static,
141 Fut: Future<Output = ()> + Send,
142 {
143 let token = CancelToken::new();
144 let wait_token = token.clone();
145 let mut rx = self.state_rx.clone();
146 let listen = async move {
147 loop {
148 tokio::select! {
149 _ = wait_token.cancelled() => break,
150 result = rx.changed() => {
151 match result {
152 Ok(())=>{
153 let state = rx.borrow_and_update().to_owned();
154 op(state).await;
155 }
156
157 Err(_) => break}
158 }
159 }
160 }
161 };
162 tokio::spawn(listen);
163 token
164 }
165 /// 异步监听进度变化。
166 ///
167 /// 每次进度变化时调用 `op`。进度是 `watch` 语义,**中间值可能被跳过**,
168 /// 只保证拿到的是当时的最新值;返回的 [`CancelToken`] 调用 `cancel()` 后停止监听。
169 ///
170 /// # 注意
171 ///
172 /// 与 [`ActorHandle::state_listen_async`] 相同:内部 `tokio::spawn`,需要 tokio runtime。
173 /// 同步宿主请改用 [`progress_rx`](ActorHandle::progress_rx)(`watch::Receiver`,自己每帧拉)
174 /// 或 [`get_progress`](ActorHandle::get_progress)(取当前快照)。
175 pub fn progress_listen_async<F, Fut>(&self, mut op: F) -> CancelToken
176 where
177 F: FnMut(A::Progress) -> Fut + Send + 'static,
178 Fut: Future<Output = ()> + Send,
179 {
180 let token = CancelToken::new();
181 let wait_token = token.clone();
182 let mut rx = self.progress_rx.clone();
183 let listen = async move {
184 loop {
185 tokio::select! {
186 _ = wait_token.cancelled() => break,
187 result = rx.changed() => {
188 match result {
189 Ok(())=>{
190 let progress = rx.borrow_and_update().to_owned();
191 op(progress).await;
192 }
193 Err(_) => break}
194 }
195 }
196 }
197 };
198 tokio::spawn(listen);
199 token
200 }
201 /// 异步监听事件流。
202 ///
203 /// 每收到一个事件调用一次 `op`。落后超过事件通道容量时会收到 `Lagged`,
204 /// 内部只记一条 warn 然后继续(**丢事件**,不重放);返回的 [`CancelToken`]
205 /// 调用 `cancel()` 后停止监听。
206 ///
207 /// # 注意
208 ///
209 /// 与 [`ActorHandle::state_listen_async`] 相同:内部 `tokio::spawn`,需要 tokio runtime。
210 pub fn events_listen_async<F, Fut>(&self, mut op: F) -> CancelToken
211 where
212 F: FnMut(A::Event) -> Fut + Send + 'static,
213 Fut: Future<Output = ()> + Send,
214 {
215 let mut rx = self.event_tx.subscribe();
216 let token = CancelToken::new();
217 let wait_token = token.clone();
218 let listen = async move {
219 loop {
220 tokio::select! {
221 _ = wait_token.cancelled() => break,
222 result = rx.recv() => {
223 match result {
224 Ok(e) => { op(e).await; }
225 Err(broadcast::error::RecvError::Closed) => break,
226 Err(broadcast::error::RecvError::Lagged(n)) => {
227 warn!("事件监听落后 {n} 条");
228 continue;
229 }
230 }}
231 }
232 }
233 };
234 tokio::spawn(listen);
235 token
236 }
237}