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 /// `watch::Receiver` 的方式自己拉:`get_state()` 轮询,或基于
136 /// `get_events_rx()` 每帧 `try_recv()`。
137 pub fn state_listen_async<F, Fut>(&self, mut op: F) -> CancelToken
138 where
139 F: FnMut(A::State) -> Fut + Send + 'static,
140 Fut: Future<Output = ()> + Send,
141 {
142 let token = CancelToken::new();
143 let wait_token = token.clone();
144 let mut rx = self.state_rx.clone();
145 let listen = async move {
146 loop {
147 tokio::select! {
148 _ = wait_token.cancelled() => break,
149 result = rx.changed() => {
150 match result {
151 Ok(())=>{
152 let state = rx.borrow_and_update().to_owned();
153 op(state).await;
154 }
155
156 Err(_) => break}
157 }
158 }
159 }
160 };
161 tokio::spawn(listen);
162 token
163 }
164 /// 异步监听进度变化。
165 ///
166 /// 每次进度变化时调用 `op`。进度是 `watch` 语义,**中间值可能被跳过**,
167 /// 只保证拿到的是当时的最新值;返回的 [`CancelToken`] 调用 `cancel()` 后停止监听。
168 ///
169 /// # 注意
170 ///
171 /// 与 [`ActorHandle::state_listen_async`] 相同:内部 `tokio::spawn`,需要 tokio runtime。
172 pub fn progress_listen_async<F, Fut>(&self, mut op: F) -> CancelToken
173 where
174 F: FnMut(A::Progress) -> Fut + Send + 'static,
175 Fut: Future<Output = ()> + Send,
176 {
177 let token = CancelToken::new();
178 let wait_token = token.clone();
179 let mut rx = self.progress_rx.clone();
180 let listen = async move {
181 loop {
182 tokio::select! {
183 _ = wait_token.cancelled() => break,
184 result = rx.changed() => {
185 match result {
186 Ok(())=>{
187 let progress = rx.borrow_and_update().to_owned();
188 op(progress).await;
189 }
190 Err(_) => break}
191 }
192 }
193 }
194 };
195 tokio::spawn(listen);
196 token
197 }
198 /// 异步监听事件流。
199 ///
200 /// 每收到一个事件调用一次 `op`。落后超过事件通道容量时会收到 `Lagged`,
201 /// 内部只记一条 warn 然后继续(**丢事件**,不重放);返回的 [`CancelToken`]
202 /// 调用 `cancel()` 后停止监听。
203 ///
204 /// # 注意
205 ///
206 /// 与 [`ActorHandle::state_listen_async`] 相同:内部 `tokio::spawn`,需要 tokio runtime。
207 pub fn events_listen_async<F, Fut>(&self, mut op: F) -> CancelToken
208 where
209 F: FnMut(A::Event) -> Fut + Send + 'static,
210 Fut: Future<Output = ()> + Send,
211 {
212 let mut rx = self.event_tx.subscribe();
213 let token = CancelToken::new();
214 let wait_token = token.clone();
215 let listen = async move {
216 loop {
217 tokio::select! {
218 _ = wait_token.cancelled() => break,
219 result = rx.recv() => {
220 match result {
221 Ok(e) => { op(e).await; }
222 Err(broadcast::error::RecvError::Closed) => break,
223 Err(broadcast::error::RecvError::Lagged(n)) => {
224 warn!("事件监听落后 {n} 条");
225 continue;
226 }
227 }}
228 }
229 }
230 };
231 tokio::spawn(listen);
232 token
233 }
234}