wordval-utils 1.0.8

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers, collection tools, retry utilities
Documentation
//! RCU 无锁并发 Map:读多写少场景的高性能容器
//!
//! 基于 `arc-swap` 的 clone-modify-swap 设计:
//! - **读**是单次原子指针加载,读者之间零争用,无锁无死锁;
//! - **写**克隆内部 map、在克隆上修改、原子换入;
//! - [`AtomicMap::rcu`] 自动重试解决多写者竞争。
//!
//! # 边界条件(诚实文档)
//!
//! - **多写者同时 `store` 会丢失更新**(后写覆盖先写):多写者场景必须用
//!   [`AtomicMap::rcu`](或把写收敛到单一任务);单写者 + 多读者可放心用
//!   `store`。
//! - **写开销 O(N)**:每次写克隆整张表,表很大或写极频繁时请改用
//!   `DashMap`(写多)或 `RwLock`。
//! - 适用:读多写少的配置表、路由表、元数据缓存。
//!
//! ```rust
//! use wordval_utils::atomic_map::AtomicMap;
//!
//! let map: AtomicMap<String, u32> = AtomicMap::new();
//! map.insert("a".into(), 1);
//! assert_eq!(map.get_cloned(&"a".to_string()), Some(1));
//! map.rcu(|m| { m.insert("b".into(), 2); });
//! assert_eq!(map.len(), 2);
//! ```

use std::fmt;
use std::hash::Hash;
use std::sync::Arc;

use ahash::AHashMap;
use arc_swap::ArcSwap;

/// 无锁读优化的并发 map(RCU 语义)
///
/// 见模块文档的使用边界:读零争用;多写者必须走 [`Self::rcu`]。
pub struct AtomicMap<K, V>(ArcSwap<AHashMap<K, V>>);

impl<K, V> AtomicMap<K, V> {
    /// 创建空 map
    pub fn new() -> Self {
        Self(ArcSwap::new(Arc::new(AHashMap::new())))
    }

    /// 返回内部表的快照守卫(读侧单次原子加载)
    ///
    /// 适合需要多次查表的场景:`map.load().get(&k)`。
    #[inline]
    pub fn load(&self) -> arc_swap::Guard<Arc<AHashMap<K, V>>> {
        self.0.load()
    }

    /// 原子替换整张表
    ///
    /// # 边界
    ///
    /// 多写者并发 `store` 会丢更新(后写覆盖先写)——多写者用 [`Self::rcu`]。
    pub fn store(&self, map: AHashMap<K, V>) {
        self.0.store(Arc::new(map));
    }
}

impl<K, V> AtomicMap<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{
    /// 原子地「读-改-写」:对内部表克隆应用 `f` 后换入
    ///
    /// CAS 失败(期间他人换入新表)自动重试,**`f` 可能被执行多次**——
    /// `f` 必须是幂等或基于克隆状态无副作用的。
    pub fn rcu<F>(&self, mut f: F)
    where
        F: FnMut(&mut AHashMap<K, V>),
    {
        self.0.rcu(|m| {
            let mut m = (**m).clone();
            f(&mut m);
            m
        });
    }

    /// 是否包含指定键
    #[inline]
    pub fn contains_key(&self, key: &K) -> bool {
        self.0.load().contains_key(key)
    }

    /// 取值(克隆语义)
    #[inline]
    pub fn get_cloned(&self, key: &K) -> Option<V> {
        self.0.load().get(key).cloned()
    }

    /// 插入键值对(克隆-换入;多写者安全)
    pub fn insert(&self, key: K, value: V) {
        self.rcu(|m| {
            m.insert(key.clone(), value.clone());
        });
    }

    /// 删除键(克隆-换入;多写者安全)
    pub fn remove(&self, key: &K) {
        self.rcu(|m| {
            m.remove(key);
        });
    }

    /// 条目数量(读侧一致性快照)
    #[inline]
    pub fn len(&self) -> usize {
        self.0.load().len()
    }

    /// 是否为空
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.0.load().is_empty()
    }
}

impl<K, V> Default for AtomicMap<K, V> {
    fn default() -> Self {
        Self::new()
    }
}

// 手写 Debug:内部 ArcSwap 对 V 无 Debug 约束,仅暴露长度
impl<K, V> fmt::Debug for AtomicMap<K, V> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let len = self.0.load().len();
        f.debug_struct("AtomicMap").field("len", &len).finish()
    }
}

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

    #[test]
    fn insert_get_remove() {
        let map: AtomicMap<String, u32> = AtomicMap::new();
        assert!(map.is_empty());
        map.insert("a".into(), 1);
        map.insert("b".into(), 2);
        assert_eq!(map.len(), 2);
        assert_eq!(map.get_cloned(&"a".to_string()), Some(1));
        assert!(map.contains_key(&"b".to_string()));
        map.remove(&"a".to_string());
        assert_eq!(map.get_cloned(&"a".to_string()), None);
        assert_eq!(map.len(), 1);
    }

    /// rcu 多写者并发:更新不丢失(对比 store 的丢更新边界)
    #[test]
    fn rcu_concurrent_writers_no_lost_update() {
        let map: Arc<AtomicMap<u32, u32>> = Arc::new(AtomicMap::new());
        let mut handles = Vec::new();
        for w in 0..8u32 {
            let map = Arc::clone(&map);
            handles.push(std::thread::spawn(move || {
                for i in 0..100u32 {
                    let v = w * 100 + i;
                    map.insert(v, v);
                }
            }));
        }
        for h in handles {
            h.join().unwrap();
        }
        assert_eq!(map.len(), 800);
    }

    #[test]
    fn store_replaces_snapshot() {
        let map: AtomicMap<u32, u32> = AtomicMap::new();
        map.insert(1, 1);
        let mut fresh = AHashMap::new();
        fresh.insert(9, 9);
        map.store(fresh);
        assert_eq!(map.len(), 1);
        assert_eq!(map.get_cloned(&9), Some(9));
        assert_eq!(map.get_cloned(&1), None);
    }

    #[test]
    fn debug_shows_len() {
        let map: AtomicMap<u32, u32> = AtomicMap::new();
        assert_eq!(format!("{map:?}"), "AtomicMap { len: 0 }");
    }
}