pub struct ActorSystem { /* private fields */ }Expand description
Actor 运行时容器(廉价 Clone,内部 Arc 共享)。
持有克隆不会自动延长 Actor 的生命周期,也不会阻止其被停止;
但丢弃全部克隆前必须调用 shutdown:
监督者恒持邮箱发送端,直接丢弃系统不会让任何 Actor 任务退出
(它们将随 tokio 运行时存活至进程结束)。用户句柄(new /
with_config 及其 Clone)在未 shutdown 时被全部丢弃且仍有
Actor 注册,会记录 warn 日志(见 Drop 实现)。
Implementations§
Source§impl ActorSystem
impl ActorSystem
Sourcepub fn new() -> Self
pub fn new() -> Self
以默认配置创建系统(tokio 实时钟,sleep_until 零装箱)。
§Panics
必须在 tokio runtime 上下文内调用(定时器驱动任务经
tokio::spawn 启动);在无 runtime 的同步上下文中调用将 panic。
Sourcepub fn with_config(config: ActorConfig) -> Self
pub fn with_config(config: ActorConfig) -> Self
Sourcepub fn with_clock(config: ActorConfig, clock: Arc<dyn Clock>) -> Self
pub fn with_clock(config: ActorConfig, clock: Arc<dyn Clock>) -> Self
Sourcepub fn config(&self) -> &ActorConfig
pub fn config(&self) -> &ActorConfig
系统配置。
Sourcepub fn is_shutdown(&self) -> bool
pub fn is_shutdown(&self) -> bool
是否已关闭。
Sourcepub fn spawn<A>(
&self,
opts: impl Into<SpawnOptions>,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>where
A: Actor,
pub fn spawn<A>(
&self,
opts: impl Into<SpawnOptions>,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>where
A: Actor,
创建并启动一个 Actor,返回类型化引用。
opts 可为 SpawnOptions,也可为 &str / ActorName(命名快捷)。
§错误
ActorError::DuplicateName名称已被占用;ActorError::SystemShutdown系统已关闭。
§Panics
必须在 tokio runtime 上下文内调用(Actor 事件循环经 tokio::spawn
启动):无 runtime 或运行期已关闭时 panic;此时注册表条目与名称由
回滚守卫清理,不留幽灵条目。
Sourcepub fn spawn_anonymous<A>(
&self,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>where
A: Actor,
pub fn spawn_anonymous<A>(
&self,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>where
A: Actor,
Sourcepub fn spawn_named<A>(
&self,
name: impl Into<ActorName>,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>where
A: Actor,
pub fn spawn_named<A>(
&self,
name: impl Into<ActorName>,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>where
A: Actor,
Sourcepub fn spawn_supervised<A, F>(
&self,
opts: impl Into<SpawnOptions>,
factory: F,
) -> Result<ActorRef<A::Message>, ActorError>
pub fn spawn_supervised<A, F>( &self, opts: impl Into<SpawnOptions>, factory: F, ) -> Result<ActorRef<A::Message>, ActorError>
Sourcepub fn find<M: ActorMsg>(&self, name: impl AsRef<str>) -> Option<ActorRef<M>>
pub fn find<M: ActorMsg>(&self, name: impl AsRef<str>) -> Option<ActorRef<M>>
按名称查找类型化引用;不存在或消息类型不匹配返回 None。
以 &str 直查(ActorName: Borrow<str>),
查询路径零分配。
Sourcepub fn find_by_id<M: ActorMsg>(&self, id: ActorId) -> Option<ActorRef<M>>
pub fn find_by_id<M: ActorMsg>(&self, id: ActorId) -> Option<ActorRef<M>>
按 ID 查找类型化引用(消息类型不匹配返回 None)。
Sourcepub fn actor_count(&self) -> usize
pub fn actor_count(&self) -> usize
当前注册 Actor 数量。
Sourcepub fn stop(&self, id: ActorId) -> bool
pub fn stop(&self, id: ActorId) -> bool
请求停止指定 Actor(控制面信号,邮箱满也能送达)。
非阻塞;返回是否找到存活条目并完成通知(false 表示 Actor
不存在或已最终退出 —— 监督者不再持停止通道接收端)。
请求落值后该 Actor 相位即为
Stopped { cause: Requested }。
Sourcepub fn stop_named(&self, name: impl AsRef<str>) -> bool
pub fn stop_named(&self, name: impl AsRef<str>) -> bool
按名称请求停止。
Sourcepub async fn stop_and_wait(&self, id: ActorId) -> bool
pub async fn stop_and_wait(&self, id: ActorId) -> bool
请求停止并等待其最终退出(真正 await)。
返回 false 表示条目已不存在(Actor 早已退出,无可等待);
true 表示观察到最终退出信号(含退出信号发送端随条目释放)。
无限期等待:Actor 卡死在长 handle / on_stop 中时本调用将
永久挂起;需要上限请用
stop_and_wait_timeout。
§Panics
在目标 Actor 自身的 handle 内对自己调用会立即 panic(自调用
防护):本调用阻塞等待该 Actor 的事件循环推进退出,而事件循环正
阻塞在本调用上,必然死锁。Actor 请求自身停止请用 ActorContext::stop
加返回 ActorAction::Stop。经 tokio::spawn 转手的调用不被识别为
自调用(子任务无世代身份),仍会死锁。
Sourcepub async fn stop_and_wait_timeout(
&self,
id: ActorId,
timeout: Duration,
) -> Result<bool, ActorError>
pub async fn stop_and_wait_timeout( &self, id: ActorId, timeout: Duration, ) -> Result<bool, ActorError>
请求停止并限时等待退出。
语义同 stop_and_wait,但超过
timeout 未观察到最终退出信号时返回
ActorError::Timeout(停止请求本身已送达,Actor 可能仍在
处理收尾逻辑)。等待走系统注入时钟,虚拟时间测试可确定推进。
§Panics
自调用防护同 stop_and_wait:在目标
Actor 自身 handle 内对自己调用立即 panic(这里只会白等满
timeout 后返回 ActorError::Timeout,属必然失败的调用)。
Sourcepub async fn shutdown(&self)
pub async fn shutdown(&self)
优雅关闭整个系统:通知全部 Actor 停止并等待退出。
幂等。并发调用时仅首个调用者执行关闭流程,其余调用者立即
返回 —— 可能先于全部 Actor 真正退出;需要确定性等待请串行
调用或等待首个调用完成。关闭后
spawn 被拒绝(返回
ActorError::SystemShutdown)。超过
ActorConfig::shutdown_grace 仍未退出的 Actor 将被强制注销;
是否进一步硬终止(abort)卡死的任务由
ActorConfig::abort_on_grace_timeout 决定(默认仅注销)。
终止通知语义:因本关闭请求退出的 Actor,watcher 收到的
Terminated 原因为 StopCause::SystemShutdown(与显式
stop 的 StopCause::Requested 区分)。
§在 Actor 内部调用(自调用)
允许,且不会白等宽限期:调用者自身(世代任务)被识别并排除出
等待集 —— 它的循环正阻塞在本调用上,纳入等待只会等满
shutdown_grace 后被误判超时强制注销。停止请求仍照常送达调用者,
本调用返回后其 handle 正常返回,下一轮循环顶部见到停止位即
优雅退出(on_stop 照常执行)。
经 tokio::spawn 转手的调用(在派生任务中关系统)不被识别为
自调用(标记不跨任务继承),将退化为等待其所属 Actor 直到宽限
超时;这种接线请改为 Actor 内 ActorContext::stop /
ActorAction::Stop,由外部任务负责关闭系统。