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    /// `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}