Skip to main content

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}