wordval-actor 1.0.5

Wordval actor system: high-performance message foundation for drone ground stations
Documentation
//! Actor trait —— 消息驱动的生命周期抽象。

use crate::ctx::ActorContext;
use crate::mailbox::MailboxPolicy;
use crate::msg::{ActorMsg, ActorSignal};
use std::future::Future;

/// 消息处理结果。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ActorAction {
    /// 继续处理下一条消息。
    Continue,
    /// 优雅停止:处理完当前消息后,调用
    /// [`on_stop`](Actor::on_stop) 并退出事件循环。
    Stop,
}

/// Actor 核心抽象。
///
/// 每个 Actor 拥有一个消息类型 [`Actor::Message`] 与一条事件循环
/// (由 [`ActorSystem`](crate::ActorSystem) 托管调度)。
/// 事件循环按序处理三类输入,且**控制面永远优先**:
///
/// 1. 停止信号 / 系统信号 / 看门狗触发标记 —— 专用信号通道每轮优先抽干;
///    看门狗触发以超时消息经 [`Actor::handle`] 送达(不经 [`on_signal`](Actor::on_signal))
/// 2. 控制通道用户消息([`Actor::handle`],每轮至多批处理 64 条)
/// 3. 数据端口最新帧(仅 [`MailboxPolicy::LossTolerant`],同样经 [`handle`](Actor::handle) 送达)
///
/// 采用 RPITIT(`-> impl Future + Send`):无装箱、无 `dyn` 分发,
/// 且保证各实现方的未来跨线程可调度;实现时直接写 `async fn` 即可。
///
/// # 示例
///
/// ```
/// use wordval_actor::{Actor, ActorAction, ActorContext, MailboxPolicy};
///
/// struct Failsafe { armed: bool }
/// enum Msg { TelemetryTick, LinkLost }
///
/// impl Actor for Failsafe {
///     type Message = Msg;
///     const POLICY: MailboxPolicy = MailboxPolicy::Reliable { capacity: 64 };
///
///     async fn handle(&mut self, msg: Msg, _ctx: &mut ActorContext<Msg>) -> ActorAction {
///         match msg {
///             Msg::TelemetryTick => self.armed = true,
///             Msg::LinkLost => self.armed = false,
///         }
///         ActorAction::Continue
///     }
/// }
/// ```
pub trait Actor: Sized + Send + 'static {
    /// Actor 接收并处理的消息类型。
    type Message: ActorMsg;

    /// 邮箱策略(编译期声明)。`capacity: 0` 表示使用系统默认容量。
    const POLICY: MailboxPolicy = MailboxPolicy::DEFAULT;

    /// 邮箱策略钩子(运行期覆写,默认返回 [`POLICY`](Actor::POLICY))。
    fn mailbox_policy() -> MailboxPolicy {
        Self::POLICY
    }

    /// 处理一条用户消息(含数据端口帧与定时消息)。
    fn handle(
        &mut self,
        msg: Self::Message,
        ctx: &mut ActorContext<Self::Message>,
    ) -> impl Future<Output = ActorAction> + Send;

    /// Actor 因 panic 被监督重启后调用(新世代实例、[`on_start`](Actor::on_start)
    /// 之前;仅当上一世代以 panic 结束且策略允许重启时)。
    ///
    /// `attempt` 为连续重启序号(1 起);[`ActorContext::generation`]
    /// 可获取当前世代号,[`ActorContext::restarts`] 可获取累计重启次数。
    /// 默认空实现。
    fn on_restart(
        &mut self,
        _attempt: u32,
        _ctx: &mut ActorContext<Self::Message>,
    ) -> impl Future<Output = ()> + Send {
        async {}
    }

    /// Actor 启动时调用(在第一条消息处理之前)。默认空实现。
    fn on_start(&mut self, _ctx: &mut ActorContext<Self::Message>) -> impl Future<Output = ()> + Send {
        async {}
    }

    /// Actor 即将停止时调用(事件循环退出前)。默认空实现。
    ///
    /// 注意:事件循环因 panic 终止时不会调用此钩子,资源清理应依赖
    /// Drop 语义或监督策略。
    fn on_stop(&mut self, _ctx: &mut ActorContext<Self::Message>) -> impl Future<Output = ()> + Send {
        async {}
    }

    /// 处理系统信号(如被监视者终止通知)。默认忽略并继续。
    fn on_signal(
        &mut self,
        _sig: ActorSignal,
        _ctx: &mut ActorContext<Self::Message>,
    ) -> impl Future<Output = ActorAction> + Send {
        async { ActorAction::Continue }
    }
}