Skip to main content

ActorSystem

Struct ActorSystem 

Source
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

Source

pub fn new() -> Self

以默认配置创建系统(tokio 实时钟,sleep_until 零装箱)。

§Panics

必须在 tokio runtime 上下文内调用(定时器驱动任务经 tokio::spawn 启动);在无 runtime 的同步上下文中调用将 panic。

Source

pub fn with_config(config: ActorConfig) -> Self

以指定配置创建系统。

§Panics

同 new:必须在 tokio runtime 上下文内调用。

Source

pub fn with_clock(config: ActorConfig, clock: Arc<dyn Clock>) -> Self

注入自定义时钟(测试可虚拟时间,配合 Clock 抽象)。

§Panics

同 new:必须在 tokio runtime 上下文内调用。

Source

pub fn config(&self) -> &ActorConfig

系统配置。

Source

pub fn now(&self) -> Instant

当前时间(统一走系统时钟源,测试下即虚拟时间)。

Source

pub fn is_shutdown(&self) -> bool

是否已关闭。

Source

pub fn spawn<A>( &self, opts: impl Into<SpawnOptions>, actor: A, ) -> Result<ActorRef<A::Message>, ActorError>
where A: Actor,

创建并启动一个 Actor,返回类型化引用。

opts 可为 SpawnOptions,也可为 &str / ActorName(命名快捷)。

§错误
§Panics

必须在 tokio runtime 上下文内调用(Actor 事件循环经 tokio::spawn 启动):无 runtime 或运行期已关闭时 panic;此时注册表条目与名称由 回滚守卫清理,不留幽灵条目。

Source

pub fn spawn_anonymous<A>( &self, actor: A, ) -> Result<ActorRef<A::Message>, ActorError>
where A: Actor,

匿名 spawn(自动分配 ID)。

§Panics

同 spawn:必须在 tokio runtime 上下文内调用。

Source

pub fn spawn_named<A>( &self, name: impl Into<ActorName>, actor: A, ) -> Result<ActorRef<A::Message>, ActorError>
where A: Actor,

命名 spawn。重名返回 ActorError::DuplicateName。

§Panics

同 spawn:必须在 tokio runtime 上下文内调用。

Source

pub fn spawn_supervised<A, F>( &self, opts: impl Into<SpawnOptions>, factory: F, ) -> Result<ActorRef<A::Message>, ActorError>
where A: Actor, F: Fn() -> A + Send + Sync + 'static,

受监督的工厂 spawn:panic 后按策略用 factory 重建实例。

重启期间已入队未取的邮箱消息不丢失(信箱跨世代续存),恢复后 新世代继续消费;panic 时正在 handle 中的那条已随世代消费,不重放。 每个世代的 on_start 重新执行。

§Panics

同 spawn:必须在 tokio runtime 上下文内调用。 工厂在 spawn 期间不会被执行(首个实例在监督任务内构造),其 panic 由 catch_unwind 捕获并按监督策略处置。

Source

pub fn find<M: ActorMsg>(&self, name: impl AsRef<str>) -> Option<ActorRef<M>>

按名称查找类型化引用;不存在或消息类型不匹配返回 None。

以 &str 直查(ActorName: Borrow<str>), 查询路径零分配。

Source

pub fn find_by_id<M: ActorMsg>(&self, id: ActorId) -> Option<ActorRef<M>>

按 ID 查找类型化引用(消息类型不匹配返回 None)。

Source

pub fn resolve_name(&self, name: impl AsRef<str>) -> Option<ActorId>

名称 → ID 解析(&str 直查,零分配)。

Source

pub fn is_alive(&self, id: ActorId) -> bool

Actor 是否仍注册在系统内(终止中/已终止返回 false)。

Source

pub fn actor_count(&self) -> usize

当前注册 Actor 数量。

Source

pub fn actor_ids(&self) -> Vec<ActorId>

全部活跃 Actor 的 ID。

Source

pub fn stop(&self, id: ActorId) -> bool

请求停止指定 Actor(控制面信号,邮箱满也能送达)。

非阻塞;返回是否找到存活条目并完成通知(false 表示 Actor 不存在或已最终退出 —— 监督者不再持停止通道接收端)。 请求落值后该 Actor 相位即为 Stopped { cause: Requested }。

Source

pub fn stop_named(&self, name: impl AsRef<str>) -> bool

按名称请求停止。

Source

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 转手的调用不被识别为 自调用(子任务无世代身份),仍会死锁。

Source

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,属必然失败的调用)。

Source

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,由外部任务负责关闭系统。

Trait Implementations§

Source§

impl Clone for ActorSystem

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Default for ActorSystem

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Drop for ActorSystem

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> ActorMsg for T
where T: Send + 'static,

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more