pub struct ActorHandle<A: ActorCore> { /* private fields */ }Expand description
actor 的控制端。
由 ActorCore::channel 创建,通常由外部控制方持有。用于发送命令、读取状态/进度、
订阅事件,以及注册异步监听。
§线程安全
ActorHandle<A> 的 Send/Sync 只取决于四个关联类型,与 actor 本身是否 Send 无关:
即使 A 是 !Send(比如握着 Rc<...> 资源的线程 actor),它照样可以放进 GUI props、
跨线程传递、塞进 Arc。
§发送命令
send_cmd 是同步的:不阻塞、不返回 future,唯一的失败原因是
actor 已停止(或所有后台端已退出)。因此可以在 GUI 回调、Drop、同步宿主里直接调用。
§示例
let (context, handle) = MyActor::channel( (), ());
handle.send_cmd(()).unwrap();
let state = handle.get_state();
let listener = handle.state_listen_async(|s| async move { });
listener.cancel();Implementations§
Source§impl<A: AsyncActor> ActorHandle<A>
impl<A: AsyncActor> ActorHandle<A>
Sourcepub fn state_listen_async<F, Fut>(&self, op: F) -> CancelToken
pub fn state_listen_async<F, Fut>(&self, op: F) -> CancelToken
异步监听状态变化。
每次状态变化时会调用 op,传入最新状态;返回的 CancelToken 调用
CancelToken::cancel 后停止监听。
§注意
内部使用 tokio::spawn,调用线程必须有 tokio runtime,否则会 panic
(there is no reactor running)。同步宿主(GUI 回调、GTK/iOS 主线程等)请改用
watch::Receiver 的方式自己拉:get_state() 轮询,或基于
get_events_rx() 每帧 try_recv()。
Sourcepub fn progress_listen_async<F, Fut>(&self, op: F) -> CancelToken
pub fn progress_listen_async<F, Fut>(&self, op: F) -> CancelToken
异步监听进度变化。
每次进度变化时调用 op。进度是 watch 语义,中间值可能被跳过,
只保证拿到的是当时的最新值;返回的 CancelToken 调用 cancel() 后停止监听。
§注意
与 ActorHandle::state_listen_async 相同:内部 tokio::spawn,需要 tokio runtime。
Sourcepub fn events_listen_async<F, Fut>(&self, op: F) -> CancelToken
pub fn events_listen_async<F, Fut>(&self, op: F) -> CancelToken
异步监听事件流。
每收到一个事件调用一次 op。落后超过事件通道容量时会收到 Lagged,
内部只记一条 warn 然后继续(丢事件,不重放);返回的 CancelToken
调用 cancel() 后停止监听。
§注意
与 ActorHandle::state_listen_async 相同:内部 tokio::spawn,需要 tokio runtime。
Source§impl<A: ActorCore> ActorHandle<A>
impl<A: ActorCore> ActorHandle<A>
Sourcepub fn send_cmd(&self, cmd: A::Cmd) -> Result<(), SendCmdError>
pub fn send_cmd(&self, cmd: A::Cmd) -> Result<(), SendCmdError>
向 actor 发送一条命令。
同步、不阻塞(命令通道是无界的),不会阻塞调用线程。失败只会在 actor 已停止
(ActorHandle::stop 之后,或后台端已退出)时发生。
Sourcepub fn get_progress(&self) -> A::Progress
pub fn get_progress(&self) -> A::Progress
获取 actor 的最新进度。
进度通道是 watch:读者只会看到最新值,中间值可能被跳过。
适合进度条、实时指标,不要拿它当消息队列用。
Sourcepub fn get_events_rx(&self) -> Receiver<A::Event>
pub fn get_events_rx(&self) -> Receiver<A::Event>
订阅事件流,返回一个 broadcast 接收端。
这是同步用法:在 GUI 帧循环里 try_recv() 即可,不需要 async runtime。
落后太多时 recv() 会返回 Lagged,需要自行决定是跳过还是重试。
Sourcepub fn stop(&self)
pub fn stop(&self)
请求 actor 停止。
只是发出取消信号(CancelToken::cancel),不会强行中断 run:
实现者需要在自己的循环里检查取消信号(如 select! 到 cancel.cancelled(),
或每轮 is_cancelled()),否则 actor 会继续跑到 run 返回为止。