use crate::addr::{ActorId, ActorName};
use crate::actor::{Actor, ActorAction};
use crate::ctx::ActorContext;
use crate::mailbox::{latest_slot, SlotReader, DEFAULT_MAILBOX_CAPACITY};
use crate::msg::{
ActorMsg, ActorPhase, ActorSignal, Signal, StopCause, Terminated, publish_phase, request_stop,
};
use crate::refs::{new_ref, ActorRef};
use crate::timer::{Clock, ClockSource, TimerDriver, deadline_after};
use dashmap::DashMap;
use std::fmt;
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering as AtomicOrdering};
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::{mpsc, oneshot, watch};
const SELF_BATCH_LIMIT: usize = 64;
tokio::task_local! {
pub(crate) static GENERATION_ACTOR: ActorId;
}
pub(crate) fn assert_not_self_call(target: ActorId, what: &str) {
if let Ok(caller) = GENERATION_ACTOR.try_with(|id| *id) {
assert_ne!(
caller, target,
"检测到 Actor {target} 的 {what} 自调用:该 API 需等待目标事件循环\
推进,而事件循环正阻塞在此调用上,必然死锁或等满超时。\
请求自身停止请改用 ActorContext::stop() 并返回 ActorAction::Stop;\
确有异步需要时请在 tokio::spawn 出的独立任务中调用\
(子任务不带世代身份,不在本检测范围内)"
);
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ActorError {
DuplicateName(ActorName),
MailboxFull(ActorId),
Closed(ActorId),
Timeout(ActorId),
SystemShutdown,
}
impl fmt::Display for ActorError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ActorError::DuplicateName(n) => write!(f, "Actor 名称 \"{n}\" 已被占用"),
ActorError::MailboxFull(id) => write!(f, "Actor {id} 邮箱已满,请稍后重试"),
ActorError::Closed(id) => write!(f, "Actor {id} 通道已关闭"),
ActorError::Timeout(id) => write!(f, "Actor {id} 未在期限内退出"),
ActorError::SystemShutdown => f.write_str("ActorSystem 已关闭"),
}
}
}
impl std::error::Error for ActorError {}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum RestartPolicy {
#[default]
Permanent,
Transient {
max_restarts: u32,
backoff: Duration,
reset_after: Duration,
},
}
#[derive(Debug, Clone)]
pub struct SpawnOptions {
pub(crate) name: Option<ActorName>,
pub(crate) restart: RestartPolicy,
pub(crate) parent: Option<ActorId>,
}
impl SpawnOptions {
pub fn void() -> Self {
Self {
name: None,
restart: RestartPolicy::default(),
parent: None,
}
}
pub fn named(name: impl Into<ActorName>) -> Self {
Self {
name: Some(name.into()),
..Self::void()
}
}
pub fn with_name(mut self, name: impl Into<ActorName>) -> Self {
self.name = Some(name.into());
self
}
pub fn with_restart(mut self, policy: RestartPolicy) -> Self {
self.restart = policy;
self
}
pub(crate) fn with_parent(mut self, parent: ActorId) -> Self {
self.parent = Some(parent);
self
}
}
impl Default for SpawnOptions {
fn default() -> Self {
Self::void()
}
}
impl From<&str> for SpawnOptions {
fn from(n: &str) -> Self {
Self::named(n)
}
}
impl From<String> for SpawnOptions {
fn from(n: String) -> Self {
Self::named(n)
}
}
impl From<ActorName> for SpawnOptions {
fn from(n: ActorName) -> Self {
Self::named(n)
}
}
#[derive(Debug, Clone)]
pub struct ActorConfig {
pub mailbox_capacity: usize,
pub signal_channel_capacity: usize,
pub shutdown_grace: Duration,
pub abort_on_grace_timeout: bool,
}
impl Default for ActorConfig {
fn default() -> Self {
Self {
mailbox_capacity: DEFAULT_MAILBOX_CAPACITY,
signal_channel_capacity: SIGNAL_CHANNEL_CAPACITY,
shutdown_grace: Duration::from_secs(2),
abort_on_grace_timeout: false,
}
}
}
const SIGNAL_CHANNEL_CAPACITY: usize = 64;
trait SignalSink: Send + Sync {
fn push_signal(&self, sig: Signal);
}
impl SignalSink for mpsc::Sender<Signal> {
fn push_signal(&self, sig: Signal) {
match self.try_send(sig) {
Ok(()) => {}
Err(mpsc::error::TrySendError::Full(sig)) => {
let Ok(handle) = tokio::runtime::Handle::try_current() else {
tracing::warn!("信号通道满载且无异步上下文(系统收尾),Terminated 通知丢弃");
return;
};
let tx = self.clone();
handle.spawn(async move {
if tx.send(sig).await.is_err() {
tracing::debug!("Terminated 投递中止:信号通道已关闭(目标已终止)")
}
});
}
Err(mpsc::error::TrySendError::Closed(_)) => {
tracing::debug!("Terminated 投递中止:信号通道已关闭(目标已终止)")
}
}
}
}
trait AnyRef: Send + Sync {
fn as_any(&self) -> &dyn std::any::Any;
}
impl<M: ActorMsg> AnyRef for ActorRef<M> {
fn as_any(&self) -> &dyn std::any::Any {
self
}
}
struct Entry {
id: ActorId,
name: Option<ActorName>,
kind: &'static str,
sig: Box<dyn SignalSink>,
stop: Arc<watch::Sender<ActorPhase>>,
exit: watch::Sender<bool>,
abort: Arc<std::sync::Mutex<Option<tokio::task::AbortHandle>>>,
typed: Box<dyn AnyRef>,
}
pub(crate) struct SystemInner {
registry: DashMap<ActorId, Entry>,
by_name: DashMap<ActorName, ActorId>,
watched_by: DashMap<ActorId, Vec<ActorId>>,
watching: DashMap<ActorId, Vec<ActorId>>,
next_id: AtomicU64,
next_arm: AtomicU64,
tracked_handles: AtomicUsize,
shutdown: AtomicBool,
shutdown_tx: watch::Sender<bool>,
pub(crate) timer: TimerDriver,
clock: ClockSource,
config: ActorConfig,
}
impl SystemInner {
pub(crate) fn next_watchdog_arm(&self) -> u64 {
self.next_arm.fetch_add(1, AtomicOrdering::Relaxed)
}
fn register_name(&self, name: &ActorName, id: ActorId) -> Result<(), ActorError> {
use dashmap::mapref::entry::Entry as NameEntry;
match self.by_name.entry(name.clone()) {
NameEntry::Vacant(v) => {
v.insert(id);
Ok(())
}
NameEntry::Occupied(occupied) => {
let cur = *occupied.get();
drop(occupied);
if self.registry.contains_key(&cur) {
return Err(ActorError::DuplicateName(name.clone()));
}
self.by_name.remove_if(name, |_, &cur_id| cur_id == cur);
match self.by_name.entry(name.clone()) {
NameEntry::Vacant(v) => {
v.insert(id);
Ok(())
}
NameEntry::Occupied(_) => Err(ActorError::DuplicateName(name.clone())),
}
}
}
}
pub(crate) fn register_watch(&self, watcher: ActorId, target: ActorId) {
let mut list = self.watched_by.entry(target).or_default();
if !list.contains(&watcher) {
list.push(watcher);
}
drop(list);
let mut rev = self.watching.entry(watcher).or_default();
if !rev.contains(&target) {
rev.push(target);
}
}
pub(crate) fn unregister_watch(&self, watcher: ActorId, target: ActorId) -> bool {
let removed = match self.watched_by.get_mut(&target) {
Some(mut list) => {
let before = list.len();
list.retain(|&w| w != watcher);
let removed = list.len() != before;
let now_empty = list.is_empty();
drop(list);
if now_empty {
self.watched_by
.remove_if(&target, |_, watchers| watchers.is_empty());
}
removed
}
None => false,
};
if let Some(mut rev) = self.watching.get_mut(&watcher) {
rev.retain(|&t| t != target);
let now_empty = rev.is_empty();
drop(rev);
if now_empty {
self.watching
.remove_if(&watcher, |_, targets| targets.is_empty());
}
}
removed
}
pub(crate) fn cleanup_watcher(&self, watcher: ActorId) {
if let Some((_, targets)) = self.watching.remove(&watcher) {
for target in targets {
if let Some(mut list) = self.watched_by.get_mut(&target) {
list.retain(|&w| w != watcher);
let now_empty = list.is_empty();
drop(list);
if now_empty {
self.watched_by
.remove_if(&target, |_, watchers| watchers.is_empty());
}
}
}
}
}
fn push_signal(&self, id: ActorId, sig: ActorSignal) {
if let Some(e) = self.registry.get(&id) {
e.sig.push_signal(Signal::System(sig));
}
}
}
struct SpawnRollback {
inner: Arc<SystemInner>,
id: ActorId,
name: Option<ActorName>,
parent: Option<ActorId>,
armed: bool,
}
impl SpawnRollback {
fn disarm(&mut self) {
self.armed = false;
}
}
impl Drop for SpawnRollback {
fn drop(&mut self) {
if !self.armed {
return;
}
self.inner.registry.remove(&self.id);
if let Some(n) = &self.name {
self.inner.by_name.remove_if(n, |_, &cur| cur == self.id);
}
if let Some(parent) = self.parent {
self.inner.unregister_watch(parent, self.id);
}
tracing::debug!(actor = %self.id, "spawn 未完成,已回滚注册表与名称登记");
}
}
pub struct ActorSystem {
pub(crate) inner: Arc<SystemInner>,
tracked: bool,
}
impl Clone for ActorSystem {
fn clone(&self) -> Self {
if self.tracked {
self.inner
.tracked_handles
.fetch_add(1, AtomicOrdering::Relaxed);
}
Self {
inner: self.inner.clone(),
tracked: self.tracked,
}
}
}
impl Drop for ActorSystem {
fn drop(&mut self) {
if !self.tracked || self.inner.tracked_handles.fetch_sub(1, AtomicOrdering::AcqRel) != 1 {
return; }
let alive = self.inner.registry.len();
if alive > 0 && !self.inner.shutdown.load(AtomicOrdering::Acquire) {
tracing::warn!(
actor_count = alive,
"ActorSystem 的最后一个句柄在未调用 shutdown 的情况下被丢弃:\
{alive} 个 Actor 任务将继续运行(监督者恒持邮箱发送端)\
直至 tokio 运行时销毁,请改调 ActorSystem::shutdown"
);
}
}
}
impl ActorSystem {
pub fn new() -> Self {
Self::with_config(ActorConfig::default())
}
pub fn with_config(config: ActorConfig) -> Self {
Self::with_clock_source(config, ClockSource::Tokio)
}
pub fn with_clock(config: ActorConfig, clock: Arc<dyn Clock>) -> Self {
Self::with_clock_source(config, ClockSource::Custom(clock))
}
fn with_clock_source(config: ActorConfig, clock: ClockSource) -> Self {
let timer = TimerDriver::spawn(clock.clone());
let (shutdown_tx, _) = watch::channel(false);
Self {
inner: Arc::new(SystemInner {
registry: DashMap::new(),
by_name: DashMap::new(),
watched_by: DashMap::new(),
watching: DashMap::new(),
next_id: AtomicU64::new(1),
next_arm: AtomicU64::new(1),
tracked_handles: AtomicUsize::new(1),
shutdown: AtomicBool::new(false),
shutdown_tx,
timer,
clock,
config,
}),
tracked: true,
}
}
pub(crate) fn from_inner(inner: Arc<SystemInner>) -> Self {
Self {
inner,
tracked: false,
}
}
fn internal(&self) -> Self {
Self::from_inner(self.inner.clone())
}
pub fn config(&self) -> &ActorConfig {
&self.inner.config
}
pub fn now(&self) -> tokio::time::Instant {
self.inner.clock.now()
}
pub fn is_shutdown(&self) -> bool {
self.inner.shutdown.load(AtomicOrdering::Acquire)
}
pub fn spawn<A>(
&self,
opts: impl Into<SpawnOptions>,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>
where
A: Actor,
{
self.spawn_inner(opts.into(), ActorSource::Once(Some(actor)))
}
pub fn spawn_anonymous<A>(&self, actor: A) -> Result<ActorRef<A::Message>, ActorError>
where
A: Actor,
{
self.spawn(SpawnOptions::void(), actor)
}
pub fn spawn_named<A>(
&self,
name: impl Into<ActorName>,
actor: A,
) -> Result<ActorRef<A::Message>, ActorError>
where
A: Actor,
{
self.spawn(SpawnOptions::named(name), actor)
}
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,
{
self.spawn_inner(opts.into(), ActorSource::Factory(Arc::new(factory)))
}
fn spawn_inner<A>(
&self,
opts: SpawnOptions,
source: ActorSource<A>,
) -> Result<ActorRef<A::Message>, ActorError>
where
A: Actor,
{
let inner = self.inner.clone();
if self.is_shutdown() {
return Err(ActorError::SystemShutdown);
}
if matches!(source, ActorSource::Once(_))
&& matches!(opts.restart, RestartPolicy::Transient { .. })
{
tracing::warn!(
"spawn 使用一次性实例但声明了 Transient 策略;panic 后将无法重启(请改用 spawn_supervised)"
);
}
let id = ActorId::new(inner.next_id.fetch_add(1, AtomicOrdering::Relaxed));
let name = opts.name.clone();
let policy = A::mailbox_policy().resolve(inner.config.mailbox_capacity);
let (ctl_tx, ctl_rx) = mpsc::channel::<A::Message>(policy.capacity());
let (sig_tx, sig_rx) = mpsc::channel::<Signal>(inner.config.signal_channel_capacity.max(1));
let (stop_tx, stop_rx) = watch::channel(ActorPhase::Running);
let stop_tx = Arc::new(stop_tx);
let (slot_tx, slot_rx) = if policy.has_data_port() {
let (w, r) = latest_slot::<A::Message>();
(Some(w), Some(r))
} else {
(None, None)
};
let (exit_tx, _) = watch::channel(false);
let abort_slot: Arc<std::sync::Mutex<Option<tokio::task::AbortHandle>>> =
Arc::new(std::sync::Mutex::new(None));
let aref = new_ref(
id,
name.clone(),
ctl_tx.clone(),
stop_tx.clone(),
slot_tx,
inner.clock.clone(),
Arc::downgrade(&inner),
);
tracing::debug!(actor = %id, kind = std::any::type_name::<A::Message>(), capacity = policy.capacity(), "Actor 已注册");
inner.registry.insert(
id,
Entry {
id,
name: name.clone(),
kind: std::any::type_name::<A::Message>(),
sig: Box::new(sig_tx.clone()),
stop: stop_tx.clone(),
exit: exit_tx.clone(),
abort: abort_slot.clone(),
typed: Box::new(aref.clone()),
},
);
let mut rollback = SpawnRollback {
inner: inner.clone(),
id,
name: name.clone(),
parent: opts.parent,
armed: true,
};
if let Some(n) = &name {
inner.register_name(n, id)?;
}
if let Some(parent) = opts.parent {
inner.register_watch(parent, id);
}
let guard = FinalizeGuard {
system: self.internal(),
id,
name: name.clone(),
exit_tx,
stop_tx: stop_tx.clone(),
done: false,
};
let supervisor = Supervisor {
system: self.internal(),
id,
name: name.clone(),
source,
policy: opts.restart,
ctl_tx,
stop_tx,
stop_rx,
slot_rx,
generation: 0, restarts: 0,
mailbox: Arc::new(tokio::sync::Mutex::new(ctl_rx)),
sigbox: Arc::new(tokio::sync::Mutex::new(sig_rx)),
sig_tx: sig_tx.clone(),
abort: abort_slot,
guard,
shutdown_rx: inner.shutdown_tx.subscribe(),
};
tokio::spawn(async move { supervisor.run().await });
rollback.disarm();
Ok(aref)
}
pub fn find<M: ActorMsg>(&self, name: impl AsRef<str>) -> Option<ActorRef<M>> {
let id = *self.inner.by_name.get(name.as_ref())?;
self.find_by_id::<M>(id)
}
pub fn find_by_id<M: ActorMsg>(&self, id: ActorId) -> Option<ActorRef<M>> {
self.inner.registry.get(&id).and_then(|e| {
e.typed
.as_any()
.downcast_ref::<ActorRef<M>>()
.cloned()
})
}
pub fn resolve_name(&self, name: impl AsRef<str>) -> Option<ActorId> {
self.inner.by_name.get(name.as_ref()).map(|r| *r)
}
pub fn is_alive(&self, id: ActorId) -> bool {
self.inner.registry.contains_key(&id)
}
pub fn actor_count(&self) -> usize {
self.inner.registry.len()
}
pub fn actor_ids(&self) -> Vec<ActorId> {
self.inner.registry.iter().map(|e| *e.key()).collect()
}
#[must_use = "返回是否成功送达停止请求(false 表示 Actor 不存在)"]
pub fn stop(&self, id: ActorId) -> bool {
match self.inner.registry.get(&id) {
Some(e) => request_stop(&e.stop, StopCause::Requested),
None => false,
}
}
#[must_use = "按名称停止的结果可能被静默忽略(false 表示未找到)"]
pub fn stop_named(&self, name: impl AsRef<str>) -> bool {
match self.resolve_name(name) {
Some(id) => self.stop(id),
None => false,
}
}
pub async fn stop_and_wait(&self, id: ActorId) -> bool {
assert_not_self_call(id, "stop_and_wait");
let rx = self.inner.registry.get(&id).map(|e| e.exit.subscribe());
let _ = self.stop(id);
match rx {
Some(mut rx) => {
let _ = rx.changed().await;
true
}
None => false,
}
}
pub async fn stop_and_wait_timeout(
&self,
id: ActorId,
timeout: Duration,
) -> Result<bool, ActorError> {
assert_not_self_call(id, "stop_and_wait_timeout");
let rx = self.inner.registry.get(&id).map(|e| e.exit.subscribe());
let _ = self.stop(id);
let Some(mut rx) = rx else {
return Ok(false);
};
let deadline = deadline_after(self.inner.clock.now(), timeout);
tokio::select! {
_ = rx.changed() => Ok(true),
_ = self.inner.clock.sleep_until(deadline) => Err(ActorError::Timeout(id)),
}
}
pub async fn shutdown(&self) {
if self
.inner
.shutdown
.compare_exchange(
false,
true,
AtomicOrdering::AcqRel,
AtomicOrdering::Acquire,
)
.is_err()
{
return; }
tracing::info!(actor_count = self.actor_count(), "ActorSystem 开始优雅关闭");
let _ = self.inner.shutdown_tx.send(true);
let caller = GENERATION_ACTOR.try_with(|id| *id).ok();
let pending: Vec<(ActorId, Option<ActorName>, watch::Receiver<bool>)> = self
.inner
.registry
.iter()
.map(|e| (e.id, e.name.clone(), e.exit.subscribe()))
.collect();
for (id, _, _) in &pending {
if let Some(e) = self.inner.registry.get(id) {
let _ = request_stop(&e.stop, StopCause::SystemShutdown);
}
}
let grace = self.inner.config.shutdown_grace;
let clock = self.inner.clock.clone();
let mut waits = tokio::task::JoinSet::new();
for (id, name, rx) in pending {
if Some(id) == caller {
tracing::debug!(actor = %id, "shutdown 由该 Actor 自身发起,跳过其退出等待");
continue;
}
let clock = clock.clone();
waits.spawn(async move {
let mut rx = rx;
let deadline = deadline_after(clock.now(), grace);
let timed_out = tokio::select! {
_ = rx.changed() => false,
_ = clock.sleep_until(deadline) => true,
};
(id, name, timed_out)
});
}
while let Some(joined) = waits.join_next().await {
match joined {
Ok((id, name, timed_out)) => {
if timed_out {
tracing::warn!(%id, ?name, "Actor 未在宽限期内退出,强制注销");
self.force_deregister(id, name.as_ref());
}
}
Err(e) => tracing::warn!("关闭等待任务异常:{e}"),
}
}
tracing::info!("ActorSystem 已完全关闭");
}
fn force_deregister(&self, id: ActorId, name: Option<&ActorName>) {
if let Some((_, entry)) = self.inner.registry.remove(&id) {
if self.inner.config.abort_on_grace_timeout {
let handle = entry.abort.lock().unwrap_or_else(|e| e.into_inner()).take();
if let Some(h) = handle {
h.abort();
tracing::warn!(
actor = %id,
kind = entry.kind,
"宽限超时:已硬终止卡死的事件循环任务(实例 Drop 立即执行,on_stop 已跳过)"
);
}
}
tracing::debug!(actor = %id, kind = entry.kind, "强制注销已捕获条目");
drop(entry); }
if let Some(n) = name {
self.inner.by_name.remove_if(n, |_, &cur| cur == id);
}
self.inner.cleanup_watcher(id);
let terminated = Terminated {
actor: id,
name: name.cloned(),
cause: StopCause::SystemShutdown,
detail: None,
};
if let Some((_, watchers)) = self.inner.watched_by.remove(&id) {
for w in watchers {
self.inner
.push_signal(w, ActorSignal::Terminated(terminated.clone()));
}
}
}
}
impl Default for ActorSystem {
fn default() -> Self {
Self::new()
}
}
enum ActorSource<A: Actor> {
Once(Option<A>),
Factory(Arc<dyn Fn() -> A + Send + Sync>),
}
impl<A: Actor> ActorSource<A> {
fn take(&mut self) -> Option<A> {
match self {
ActorSource::Once(slot) => slot.take(),
ActorSource::Factory(f) => Some(f()),
}
}
fn is_renewable(&self) -> bool {
match self {
ActorSource::Once(slot) => slot.is_some(),
ActorSource::Factory(_) => true,
}
}
}
enum SourceTaken<A: Actor> {
Ready(A),
Exhausted,
FactoryPanicked(Option<String>),
}
struct GenDone {
cause: StopCause,
}
enum GenOutcome {
Exited(GenDone),
Panicked { detail: Option<String> },
}
fn payload_text(payload: Box<dyn std::any::Any + Send>) -> Option<String> {
if let Some(s) = payload.downcast_ref::<&'static str>() {
Some((*s).to_string())
} else if let Some(s) = payload.downcast_ref::<String>() {
Some(s.clone())
} else {
Some("panicked(非文本 panic 载荷)".to_string())
}
}
fn panic_detail(je: tokio::task::JoinError) -> Option<String> {
payload_text(je.into_panic())
}
struct Supervisor<A: Actor> {
system: ActorSystem,
id: ActorId,
name: Option<ActorName>,
source: ActorSource<A>,
policy: RestartPolicy,
ctl_tx: mpsc::Sender<A::Message>,
stop_tx: Arc<watch::Sender<ActorPhase>>,
stop_rx: watch::Receiver<ActorPhase>,
slot_rx: Option<SlotReader<A::Message>>,
generation: u32,
restarts: u32,
mailbox: Arc<tokio::sync::Mutex<mpsc::Receiver<A::Message>>>,
sigbox: Arc<tokio::sync::Mutex<mpsc::Receiver<Signal>>>,
sig_tx: mpsc::Sender<Signal>,
abort: Arc<std::sync::Mutex<Option<tokio::task::AbortHandle>>>,
guard: FinalizeGuard,
shutdown_rx: watch::Receiver<bool>,
}
impl<A: Actor> Supervisor<A> {
async fn run(mut self) {
let mut last_failure: Option<tokio::time::Instant> = None;
let last_cause;
let mut last_detail: Option<String> = None;
loop {
if self.is_shutdown() {
if self.generation == 0 {
tracing::warn!(
actor = %self.id,
name = ?self.name,
"Actor 在系统关闭流程中注册,未执行 on_start/on_stop 即退出"
);
}
last_cause = StopCause::SystemShutdown;
last_detail = None;
break;
}
if matches!(
&*self.stop_rx.borrow_and_update(),
ActorPhase::Stopped { .. }
) {
last_cause = StopCause::Requested;
last_detail = None;
break;
}
let outcome = match self.take_actor() {
SourceTaken::Ready(actor) => {
self.generation += 1;
self.run_one_generation(actor).await
}
SourceTaken::Exhausted => {
last_cause = if self.restarts > 0 {
StopCause::ResourceLimit
} else {
StopCause::Panicked
};
break;
}
SourceTaken::FactoryPanicked(detail) => GenOutcome::Panicked { detail },
};
match outcome {
GenOutcome::Exited(done) => {
last_cause = if done.cause == StopCause::Requested && self.is_shutdown() {
StopCause::SystemShutdown
} else {
done.cause
};
last_detail = None;
break;
}
GenOutcome::Panicked { detail } => {
last_detail = detail;
match self.policy {
RestartPolicy::Permanent => {
last_cause = StopCause::Panicked;
break;
}
RestartPolicy::Transient {
max_restarts,
backoff,
reset_after,
} => {
let now = self.system.now();
if last_failure.is_some_and(|t| now - t >= reset_after) {
self.restarts = 0; }
self.restarts += 1;
last_failure = Some(now);
if !self.source.is_renewable() || self.restarts > max_restarts {
last_cause = StopCause::ResourceLimit;
break;
}
let shift = (self.restarts - 1).min(10);
let delay = backoff.saturating_mul(1u32 << shift);
tracing::warn!(
actor = %self.id,
restart = self.restarts,
?delay,
"Actor 事件循环 panic,按监督策略重启"
);
publish_phase(
&self.stop_tx,
ActorPhase::Restarting {
generation: self.generation + 1,
attempt: self.restarts,
},
);
if !self.wait_backoff(delay).await {
last_cause = if self.is_shutdown() {
StopCause::SystemShutdown
} else {
StopCause::Requested
};
last_detail = None;
break;
}
continue;
}
}
}
}
}
self.guard.finalize(last_cause, last_detail);
}
fn take_actor(&mut self) -> SourceTaken<A> {
match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.source.take())) {
Ok(Some(a)) => SourceTaken::Ready(a),
Ok(None) => SourceTaken::Exhausted,
Err(payload) => SourceTaken::FactoryPanicked(payload_text(payload)),
}
}
async fn run_one_generation(&mut self, actor: A) -> GenOutcome {
publish_phase(&self.stop_tx, ActorPhase::Running);
let ctx = ActorContext::new(
self.system.clone(),
self.id,
self.name.clone(),
self.ctl_tx.clone(),
self.stop_tx.clone(),
self.sig_tx.clone(),
self.generation,
self.restarts,
);
let gen = Generation {
actor,
ctx,
mailbox: self.mailbox.clone(),
sigbox: self.sigbox.clone(),
slot_rx: self.slot_rx.clone(),
stop_rx: self.stop_rx.clone(),
};
let (done_tx, done_rx) = oneshot::channel::<GenDone>();
let jh = tokio::spawn(async move {
let done = gen.run().await;
let _ = done_tx.send(done);
});
*self.abort.lock().unwrap_or_else(|e| e.into_inner()) = Some(jh.abort_handle());
let outcome = match done_rx.await {
Ok(done) => GenOutcome::Exited(done),
Err(_) => {
match jh.await {
Err(je) if je.is_panic() => GenOutcome::Panicked {
detail: panic_detail(je),
},
_ => GenOutcome::Exited(GenDone {
cause: StopCause::Requested,
}),
}
}
};
*self.abort.lock().unwrap_or_else(|e| e.into_inner()) = None;
outcome
}
async fn wait_backoff(&mut self, delay: Duration) -> bool {
let deadline = deadline_after(self.system.now(), delay);
let clock = self.system.inner.clock.clone();
if matches!(
&*self.stop_rx.borrow_and_update(),
ActorPhase::Stopped { .. }
) {
return false;
}
tokio::select! {
biased;
_ = self.stop_rx.changed() => !matches!(
&*self.stop_rx.borrow_and_update(),
ActorPhase::Stopped { .. }
),
_ = self.shutdown_rx.changed() => !self.is_shutdown(),
_ = clock.sleep_until(deadline) => true,
}
}
fn is_shutdown(&self) -> bool {
self.system.is_shutdown()
}
}
struct FinalizeGuard {
system: ActorSystem,
id: ActorId,
name: Option<ActorName>,
exit_tx: watch::Sender<bool>,
stop_tx: Arc<watch::Sender<ActorPhase>>,
done: bool,
}
impl FinalizeGuard {
fn finalize(&mut self, cause: StopCause, detail: Option<String>) {
if self.done {
return;
}
self.done = true;
let inner = self.system.inner.clone();
inner.registry.remove(&self.id);
if let Some(n) = &self.name {
inner.by_name.remove_if(n, |_, &cur| cur == self.id);
}
inner.cleanup_watcher(self.id);
let terminated = Terminated {
actor: self.id,
name: self.name.clone(),
cause,
detail,
};
if let Some((_, watchers)) = inner.watched_by.remove(&self.id) {
for w in watchers {
inner.push_signal(w, ActorSignal::Terminated(terminated.clone()));
}
}
tracing::debug!(actor = %self.id, %cause, "Actor 已最终退出");
let _ = self.stop_tx.send_replace(ActorPhase::Stopped {
cause,
detail: terminated.detail.clone(),
});
let _ = self.exit_tx.send(true);
}
}
impl Drop for FinalizeGuard {
fn drop(&mut self) {
self.finalize(
StopCause::Panicked,
Some("监督任务异常退出(未捕获 panic 或 runtime 关闭)".to_string()),
);
}
}
struct Generation<A: Actor> {
actor: A,
ctx: ActorContext<A::Message>,
mailbox: Arc<tokio::sync::Mutex<mpsc::Receiver<A::Message>>>,
sigbox: Arc<tokio::sync::Mutex<mpsc::Receiver<Signal>>>,
slot_rx: Option<SlotReader<A::Message>>,
stop_rx: watch::Receiver<ActorPhase>,
}
impl<A: Actor> Generation<A> {
async fn run(self) -> GenDone {
let id = self.ctx.id();
GENERATION_ACTOR.scope(id, self.run_scoped()).await
}
async fn run_scoped(self) -> GenDone {
let Generation {
mut actor,
mut ctx,
mailbox,
sigbox,
mut slot_rx,
mut stop_rx,
} = self;
let mut rx = mailbox.lock().await;
let mut sig = sigbox.lock().await;
if ctx.restarts() > 0 {
let attempt = ctx.restarts();
actor.on_restart(attempt, &mut ctx).await;
}
actor.on_start(&mut ctx).await;
let cause;
'gen: loop {
if matches!(&*stop_rx.borrow_and_update(), ActorPhase::Stopped { .. }) {
cause = StopCause::Requested;
break 'gen;
}
while let Ok(s) = sig.try_recv() {
if deliver_signal(&mut actor, &mut ctx, s).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
}
if let Some(frame) = slot_rx.as_mut().and_then(|r| r.take_latest()) {
if actor.handle(frame, &mut ctx).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
}
tokio::select! {
biased;
_ = stop_rx.changed() => continue 'gen,
s = sig.recv() => {
if let Some(s) = s {
if deliver_signal(&mut actor, &mut ctx, s).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
} else {
tracing::error!(actor = %ctx.id(), "信号通道意外关闭(理论不可达)");
}
}
msg = rx.recv() => {
let Some(mut msg) = msg else {
cause = StopCause::MailboxClosed;
break 'gen;
};
let mut drained = 1usize;
loop {
if actor.handle(msg, &mut ctx).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
if drained >= SELF_BATCH_LIMIT {
break;
}
while let Ok(s) = sig.try_recv() {
if deliver_signal(&mut actor, &mut ctx, s).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
}
if matches!(&*stop_rx.borrow(), ActorPhase::Stopped { .. }) {
cause = StopCause::Requested;
break 'gen;
}
if let Some(frame) = slot_rx.as_mut().and_then(|r| r.take_latest()) {
if actor.handle(frame, &mut ctx).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
if matches!(&*stop_rx.borrow(), ActorPhase::Stopped { .. }) {
cause = StopCause::Requested;
break 'gen;
}
}
drained += 1;
match rx.try_recv() {
Ok(m) => msg = m,
Err(_) => break,
}
}
}
_ = wait_slot(&mut slot_rx) => {
if let Some(frame) = slot_rx.as_mut().and_then(|r| r.take_latest()) {
if actor.handle(frame, &mut ctx).await == ActorAction::Stop {
cause = StopCause::Requested;
break 'gen;
}
}
}
}
}
drop(rx);
drop(sig);
actor.on_stop(&mut ctx).await;
GenDone { cause }
}
}
async fn deliver_signal<A: Actor>(
actor: &mut A,
ctx: &mut ActorContext<A::Message>,
signal: Signal,
) -> ActorAction {
match signal {
Signal::WatchdogFire { arm } => match ctx.take_watchdog_fire(arm) {
Some(msg) => actor.handle(msg, ctx).await,
None => ActorAction::Continue,
},
Signal::System(sig) => {
let ActorSignal::Terminated(t) = &sig;
ctx.reap_watch(t.actor);
actor.on_signal(sig, ctx).await
}
}
}
async fn wait_slot<M: ActorMsg>(slot_rx: &mut Option<SlotReader<M>>) -> bool {
match slot_rx {
Some(r) => {
if r.changed().await.is_ok() {
return true;
}
if r.take_latest().is_some() {
return true;
}
std::future::pending::<()>().await;
unreachable!("pending() 永不完成")
}
None => {
std::future::pending::<()>().await;
unreachable!("pending() 永不完成")
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::ctx::ActorContext;
#[tokio::test]
async fn reap_watch_clears_both_indexes() {
let system = ActorSystem::new();
let watcher = ActorId::new(900);
let target = ActorId::new(901);
system.inner.register_watch(watcher, target);
assert_eq!(
system.inner.watching.get(&watcher).map(|l| l.len()),
Some(1),
"登记后 watching 应持有目标"
);
assert_eq!(
system.inner.watched_by.get(&target).map(|l| l.len()),
Some(1),
"登记后 watched_by 应持有 watcher"
);
let (ctl_tx, _ctl_rx) = mpsc::channel::<u64>(1);
let (stop_tx, _stop_rx) = watch::channel(ActorPhase::Running);
let (sig_tx, _sig_rx) = mpsc::channel::<Signal>(1);
let mut ctx: ActorContext<u64> = ActorContext::new(
system.clone(),
watcher,
None,
ctl_tx,
Arc::new(stop_tx),
sig_tx,
1,
0,
);
ctx.reap_watch(target);
ctx.reap_watch(target);
assert!(
system.inner.watching.get(&watcher).is_none(),
"reap 后 watching 登记应被清除"
);
assert!(
system.inner.watched_by.get(&target).is_none(),
"reap 后 watched_by 登记应被清除"
);
system.shutdown().await;
}
#[test]
fn dropping_last_handle_without_shutdown_warns() {
#[derive(Clone)]
struct Buf(Arc<std::sync::Mutex<Vec<u8>>>);
impl Buf {
fn text(&self) -> String {
String::from_utf8_lossy(&self.0.lock().unwrap()).into_owned()
}
}
impl std::io::Write for Buf {
fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
self.0.lock().unwrap().extend_from_slice(data);
Ok(data.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Buf {
type Writer = Buf;
fn make_writer(&'a self) -> Buf {
self.clone()
}
}
struct Nop;
impl Actor for Nop {
type Message = u32;
async fn handle(&mut self, _m: u32, _c: &mut ActorContext<u32>) -> ActorAction {
ActorAction::Continue
}
}
let buf = Buf(Arc::new(std::sync::Mutex::new(Vec::new())));
let subscriber = tracing_subscriber::fmt()
.with_writer(buf.clone())
.with_ansi(false)
.with_max_level(tracing::Level::WARN)
.finish();
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap();
tracing::subscriber::with_default(subscriber, || {
rt.block_on(async {
let system = ActorSystem::new();
let leaked = system.spawn_anonymous(Nop).unwrap();
drop(system);
let system = ActorSystem::new();
let graceful = system.spawn_anonymous(Nop).unwrap();
system.shutdown().await;
drop(graceful);
drop(system);
drop(leaked);
});
});
let logs = buf.text();
assert_eq!(
logs.matches("未调用 shutdown").count(),
1,
"仅未 shutdown 的丢弃应告警一次;实际日志:{logs}"
);
}
#[tokio::test]
async fn wait_slot_on_closed_port_drains_last_frame_then_hangs() {
let (w, r) = latest_slot::<u32>();
w.send(7);
drop(w);
let mut slot = Some(r);
assert!(wait_slot(&mut slot).await, "关闭前最后一帧必须被补取");
assert_eq!(slot.as_mut().unwrap().take_latest(), Some(7));
let hung = tokio::time::timeout(Duration::from_millis(50), wait_slot(&mut slot)).await;
assert!(hung.is_err(), "空槽 + 写端消失必须永久挂起而非返回");
let mut none: Option<SlotReader<u32>> = None;
let hung = tokio::time::timeout(Duration::from_millis(50), wait_slot(&mut none)).await;
assert!(hung.is_err(), "无数据端口的 Actor 必须永久挂起");
}
}