wordval-actor 1.0.5

Wordval actor system: high-performance message foundation for drone ground stations
Documentation
//! 邮箱层 —— 双通道模型:有界控制通道 + 单槽数据通道。
//!
//! 每个 Actor 拥有一条**控制通道**(有界 MPSC,承载用户消息),
//! [`MailboxPolicy::LossTolerant`] 策略的 Actor 额外配备一条
//! **数据端口**([`latest_slot`],单槽 latest-value-wins)。
//!
//! 遥测帧(100-1000Hz)写入单槽:内存占用 O(1) 与帧率解耦,
//! 读取端永远拿到最新帧 —— 旧帧被覆盖而非排队;排队陈旧姿态数据
//! 只会增加延迟、毫无价值。

use crate::msg::ActorMsg;
use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering};
use std::sync::{Arc, Mutex};
use tokio::sync::watch;

/// 每个 Actor 的默认控制通道容量([`MailboxPolicy`] 中 `capacity: 0` 时生效)。
pub const DEFAULT_MAILBOX_CAPACITY: usize = 256;

/// 邮箱策略 —— 在 [`Actor`](crate::Actor) 的关联常量中声明。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MailboxPolicy {
    /// 可靠通道:指令/事件类消息,满时 `try_send` 返回
    /// [`ActorError::MailboxFull`](crate::ActorError::MailboxFull) 形成背压。
    ///
    /// `capacity` 为 0 表示使用系统默认容量。
    Reliable { capacity: usize },
    /// 容忍帧丢失:在可靠控制通道之外,附加 [`latest_slot`] 数据端口
    /// 承载高频遥测(写端覆盖、读端永远取最新)。
    ///
    /// `capacity` 为 0 表示使用系统默认容量。
    LossTolerant { capacity: usize },
}

impl MailboxPolicy {
    /// 默认策略:可靠通道,系统默认容量。
    pub const DEFAULT: Self = MailboxPolicy::Reliable { capacity: 0 };

    /// 返回控制通道容量声明(0 = 系统默认)。
    pub fn capacity(&self) -> usize {
        match self {
            MailboxPolicy::Reliable { capacity } | MailboxPolicy::LossTolerant { capacity } => {
                *capacity
            }
        }
    }

    /// 是否附带数据端口。
    pub fn has_data_port(&self) -> bool {
        matches!(self, MailboxPolicy::LossTolerant { .. })
    }

    /// 将 `capacity: 0` 解析为系统默认值(显式声明的容量原样尊重),并保证至少为 1。
    pub fn resolve(self, default_capacity: usize) -> Self {
        let declared = self.capacity();
        let cap = if declared == 0 {
            default_capacity
        } else {
            declared
        }
        .max(1);
        match self {
            MailboxPolicy::Reliable { .. } => MailboxPolicy::Reliable { capacity: cap },
            MailboxPolicy::LossTolerant { .. } => MailboxPolicy::LossTolerant { capacity: cap },
        }
    }
}

impl Default for MailboxPolicy {
    fn default() -> Self {
        Self::DEFAULT
    }
}

/// 共享槽内部状态:值单元 + 全局唯一递增序号。
///
/// `seq` 独立于 watch 通道维护:多生产者并发写入时,
/// `fetch_add` 保证每次 send 的 watch 值唯一递增,
/// 绝不因竞态算出重复值而被 watch 的等值抑制丢唤醒。
struct SlotInner<M: ActorMsg> {
    cell: Mutex<Option<M>>,
    seq: AtomicU64,
}

/// 数据端口写端 —— 可克隆、多生产者,每次写入覆盖上一帧。
pub struct SlotWriter<M: ActorMsg> {
    seq: watch::Sender<u64>,
    inner: Arc<SlotInner<M>>,
}

impl<M: ActorMsg> Clone for SlotWriter<M> {
    fn clone(&self) -> Self {
        Self {
            seq: self.seq.clone(),
            inner: self.inner.clone(),
        }
    }
}

impl<M: ActorMsg> SlotWriter<M> {
    /// 写入一帧(覆盖槽中旧帧)。返回 false 表示读端已全部消失。
    ///
    /// 毒化处理与插件层一致(`into_inner` 继续取值):临界区极小,
    /// 持锁 panic 几乎不可能,但一旦发生不应静默丢帧。
    pub fn send(&self, msg: M) -> bool {
        // 序号分配与写槽同锁序:多写者交错时「持锁顺序 == 序号顺序」,
        // 后持锁者必持更大序号,槽内永远是最新帧。序号曾分配在锁外,
        // 锁序可逆于序号时旧帧会覆盖新帧,读者经 changed() 读到陈旧帧。
        // watch 值仍随序号唯一递增,每次写入必产生一次 changed 通知。
        let (n, old) = {
            let mut g = self.inner.cell.lock().unwrap_or_else(|e| e.into_inner());
            let n = self.inner.seq.fetch_add(1, AtomicOrdering::Relaxed) + 1;
            // 旧帧在此取出(非析构):随守卫结束移出临界区,用户 M 的
            // Drop 不得在持锁期间运行
            (n, g.replace(msg))
        };
        drop(old);
        self.seq.send(n).is_ok()
    }

    /// 槽是否已无读端。
    pub fn is_closed(&self) -> bool {
        self.seq.receiver_count() == 0
    }
}

/// 数据端口读端 —— Actor 事件循环专用。
///
/// 克隆拷贝当前"已见"版本,此后各克隆的 `changed()` 通知游标独立推进;
/// 但数据槽是**共享且消费式**的 —— `take_latest` 被任一克隆取走后,
/// 其余克隆只能取到 `None`。常规用法是每 Actor 只在事件循环里持有那一个。
pub struct SlotReader<M: ActorMsg> {
    rx: watch::Receiver<u64>,
    inner: Arc<SlotInner<M>>,
}

impl<M: ActorMsg> Clone for SlotReader<M> {
    fn clone(&self) -> Self {
        Self {
            rx: self.rx.clone(),
            inner: self.inner.clone(),
        }
    }
}

impl<M: ActorMsg> SlotReader<M> {
    /// 等待下一帧写入。写端消失后返回 Err。
    pub async fn changed(&mut self) -> Result<(), watch::error::RecvError> {
        self.rx.changed().await
    }

    /// 取走当前帧(消费式,无需 `M: Clone`)。槽空时返回 None。
    pub fn take_latest(&mut self) -> Option<M> {
        self.rx.borrow_and_update();
        let mut g = self.inner.cell.lock().unwrap_or_else(|e| e.into_inner());
        g.take()
    }
}

/// 创建一对单槽数据端口(写端 + 读端)。
pub fn latest_slot<M: ActorMsg>() -> (SlotWriter<M>, SlotReader<M>) {
    let (seq, rx) = watch::channel(0u64);
    let inner = Arc::new(SlotInner {
        cell: Mutex::new(None),
        seq: AtomicU64::new(0),
    });
    (
        SlotWriter {
            seq,
            inner: inner.clone(),
        },
        SlotReader { rx, inner },
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn policy_resolve_fills_default() {
        let p = MailboxPolicy::Reliable { capacity: 0 }.resolve(128);
        assert_eq!(p, MailboxPolicy::Reliable { capacity: 128 });
        let p = MailboxPolicy::LossTolerant { capacity: 4 }.resolve(128);
        assert_eq!(p, MailboxPolicy::LossTolerant { capacity: 4 });
        assert!(p.has_data_port());
    }

    #[tokio::test]
    async fn slot_keeps_only_latest() {
        let (w, mut r) = latest_slot::<u64>();
        assert!(r.take_latest().is_none());
        for i in 0..100 {
            assert!(w.send(i));
        }
        // 消费式取最新:拿到的是最后一帧
        assert_eq!(r.take_latest(), Some(99));
        // 取走后槽为空
        assert_eq!(r.take_latest(), None);
    }

    #[tokio::test]
    async fn slot_change_notification() {
        let (w, mut r) = latest_slot::<String>();
        let handle = tokio::spawn(async move {
            r.changed().await.unwrap();
            r.take_latest()
        });
        w.send("attitude".into());
        assert_eq!(handle.await.unwrap(), Some("attitude".to_string()));
    }

    #[tokio::test]
    async fn slot_multi_writer_no_missed_wakeup() {
        // 回归:多写端并发覆盖写,每次写入都必须产生 changed 通知,
        // 读端最终必然取到最后写入的帧(等值抑制不得丢唤醒)
        let (w1, mut r) = latest_slot::<u64>();
        let w2 = w1.clone();
        let reader = tokio::spawn(async move {
            r.changed().await.unwrap();
            r.take_latest()
        });
        let h1 = tokio::spawn(async move {
            for i in 0..1000u64 {
                w1.send(i * 2);
            }
        });
        let h2 = tokio::spawn(async move {
            for i in 0..1000u64 {
                w2.send(i * 2 + 1);
            }
        });
        let _ = tokio::join!(h1, h2);
        let got = reader.await.unwrap().expect("唤醒后应取到帧");
        assert!(got >= 999, "最终帧应来自最后一批写入,实际 {got}");
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn slot_multi_writer_high_frequency_interleave() {
        // 回归(陈旧帧):序号曾分配在 cell 锁外,两写者交错时锁序可逆于
        // 序号——旧帧后写覆盖新帧,读者读回已过期帧。修复后「持锁顺序 ==
        // 序号顺序」由结构保证。该缺陷的竞态窗口正是被移除的锁间间隙,
        // 线程外部无法确定性复现,此处以高频多写者交错压测做统计性回归
        // (读端持续消费不阻塞写端,放大写写交错概率),并核对消费语义。
        let (w, mut r) = latest_slot::<u64>();
        let reader = tokio::spawn(async move {
            let mut wakes = 0u64;
            loop {
                if r.changed().await.is_err() {
                    break;
                }
                let _ = r.take_latest();
                wakes += 1;
            }
            wakes
        });
        const WRITERS: u64 = 3;
        const PER_WRITER: u64 = 5000;
        let mut handles = Vec::new();
        for base in 0..WRITERS {
            let w = w.clone();
            handles.push(tokio::spawn(async move {
                for i in 0..PER_WRITER {
                    w.send(base * PER_WRITER + i);
                }
            }));
        }
        drop(w); // 全部写端消失 → 读端 changed() 返回 Err 收尾
        for h in handles {
            h.await.unwrap();
        }
        let wakes = reader.await.unwrap();
        assert!(wakes > 0, "压测应产生至少一次唤醒");
    }

    #[test]
    fn slot_non_cloneable_msg() {
        // 消息无需 Clone:消费式 take
        struct NoClone(Box<[u8; 32]>);
        let (w, mut r) = latest_slot::<NoClone>();
        w.send(NoClone(Box::new([7u8; 32])));
        let taken = r.take_latest().expect("应取到唯一帧");
        assert_eq!(taken.0[0], 7);
    }
}