wordval-actor 1.0.5

Wordval actor system: high-performance message foundation for drone ground stations
Documentation
//! ActorPlugin —— wordval 插件系统集成。
//!
//! 两处关键契约:
//! - 全局句柄为 `Mutex<Option<ActorSystem>>` 可重启槽位:`stop` 真正
//!   shutdown 并释放句柄,再次 `start` 重建全新系统(无 OnceLock 毒化)。
//! - 配置(mailbox_capacity / shutdown_grace)真正传入
//!   [`ActorSystem::with_config`],启动参数必须实际生效。

use crate::system::{ActorConfig, ActorSystem};
use async_trait::async_trait;
use std::sync::{Mutex, OnceLock};
use wordval_core::Result;

/// 全局系统槽。`OnceLock<Mutex<Option<_>>>` 仅用于槽位本身的懒初始化,
/// 槽内内容随 start/stop 反复装填/清空,支持系统整体重启。
static GLOBAL: OnceLock<Mutex<Option<ActorSystem>>> = OnceLock::new();

fn slot() -> &'static Mutex<Option<ActorSystem>> {
    GLOBAL.get_or_init(|| Mutex::new(None))
}

/// 获取当前全局 ActorSystem。
///
/// # Panics
///
/// 若 [`ActorPlugin`] 尚未启动(或已停止),panic 并提示装配顺序。
pub fn actor_system() -> ActorSystem {
    try_actor_system().expect("ActorSystem 未就绪,请确保 ActorPlugin 已启动且未停止")
}

/// 尝试获取当前全局 ActorSystem(不 panic);未启动/已停止返回 None。
pub fn try_actor_system() -> Option<ActorSystem> {
    slot().lock().unwrap_or_else(|e| e.into_inner()).clone()
}

/// wordval Actor 插件:管理全局 [`ActorSystem`] 生命周期。
///
/// # 示例
///
/// ```no_run
/// use wordval_actor::{ActorConfig, ActorPlugin};
/// use wordval_core::plugin::PluginManager;
///
/// # async fn demo() -> wordval_core::Result<()> {
/// let plugin = ActorPlugin::new().with_config(ActorConfig {
///     mailbox_capacity: 512,
///     ..Default::default()
/// });
/// let mgr = PluginManager::new().add(plugin);
/// mgr.start_all().await?;
/// # Ok(())
/// # }
/// ```
pub struct ActorPlugin {
    config: ActorConfig,
}

impl ActorPlugin {
    /// 以默认配置创建插件。
    pub fn new() -> Self {
        Self {
            config: ActorConfig::default(),
        }
    }

    /// 指定系统配置(在 `start` 时生效)。
    pub fn with_config(mut self, config: ActorConfig) -> Self {
        self.config = config;
        self
    }

    /// 快捷设置控制通道默认容量。
    pub fn with_mailbox_capacity(mut self, capacity: usize) -> Self {
        self.config.mailbox_capacity = capacity.max(1);
        self
    }
}

impl Default for ActorPlugin {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl wordval_core::Plugin for ActorPlugin {
    fn name(&self) -> &str {
        "actor"
    }

    async fn start(&self) -> Result<()> {
        let system = ActorSystem::with_config(self.config.clone());
        // 上一次 stop 未执行(异常路径):先无锁关闭旧系统,再装填新的
        // (sync Mutex guard 绝不跨 await,否则 Future 非 Send)
        let stale = slot().lock().unwrap_or_else(|e| e.into_inner()).take();
        if let Some(old) = stale {
            old.shutdown().await;
        }
        *slot().lock().unwrap_or_else(|e| e.into_inner()) = Some(system);
        tracing::info!(
            mailbox_capacity = self.config.mailbox_capacity,
            "ActorPlugin 已启动(ActorSystem 就绪)"
        );
        Ok(())
    }

    async fn stop(&self) -> Result<()> {
        let system = slot().lock().unwrap_or_else(|e| e.into_inner()).take();
        match system {
            Some(system) => {
                system.shutdown().await;
                tracing::info!("ActorPlugin 已停止(ActorSystem 已关闭)");
            }
            None => {
                tracing::warn!("ActorPlugin stop 调用时系统未启动,忽略");
            }
        }
        Ok(())
    }

    fn priority(&self) -> i32 {
        50 // 框架基础设施,应在业务插件之前启动
    }
}