type Map struct {
    // 只有操作 dirty 的时候才使用
    mu Mutex

    // 存储当前可安全并发访问的 map 部分，通过原子指针保存。
    read atomic.Pointer[readOnly]
    
    // 是一个非线程安全的map,不仅包含新写入的key还包含read当中还没有删除掉的key。
    // 保存需要加锁的 map 部分，存储频繁修改的项。
    dirty map[any]*entry

    // 计数那些在 read map 中未找到的读取次数
    misses int
}

// readOnly is an immutable struct stored atomically in the Map.read field.
type readOnly struct {
    // 内部的只读 map, 不可变
    m       map[any]*entry
    // 如果 dirty 里 [有] readOnly.m 没有的数据, 它就是true
    amended bool
}

// 代表map中的一个key
type entry struct {
    // p 指向具体的值，有3种状态
    // 存活状态: 指向具体的值
    // nil: 说明被 Delete 删除了, 但还在 map 结构里
    // expunged(特殊标记): 说明被彻底删除了, 并且不在当前的 dirty map 里。
    p atomic.Pointer[any]
}

// Store sets the value for a key.
func (m *Map) Store(key, value any) {
    _, _ = m.Swap(key, value)
}

func (e *entry) trySwap(i *any) (*any, bool) {
    for {
        // p有3种状态, nil, 存活->实际值, expunged
        p := e.p.Load()
        // 【重点】如果是 expunged，拒绝操作，必须去慢路径处理
        if p == expunged {
            return nil, false
        }
        // CAS 尝试把旧值 p 换成新值 i
        if e.p.CompareAndSwap(p, i) {
            return p, true
        }
    }
}

// Swap swaps the value for a key and returns the previous value if any.
// The loaded result reports whether the key was present.
func (m *Map) Swap(key, value any) (previous any, loaded bool) {
    // 快路径: 加载只读部分的当前状态 - readmap
    read := m.loadReadOnly()
    if e, ok := read.m[key]; ok {
        // 如果在只读 map 中找到了条目, 就尝试更新value
        if v, ok := e.trySwap(&value); ok {
            if v == nil {
                return nil, false
            }
            // 旧value
            return *v, true
        }
    }
    
    // 如果 key 不在 readmap 里, 或者被标记成 expunged, 就会进入慢路径
    // 慢路径: 加锁
    
    m.mu.Lock()
    // double-check: 在加锁后重新读一次 read，防止在等待锁的过程中 dirty 被提升为了 read
    read = m.loadReadOnly()
    
    if e, ok := read.m[key]; ok {
        // ------------------------------------------------------
        // 分支 A：Key 在 Read Map 中
        // (这种情况通常是因为 Fast Path 遇到了 expunged 状态)
        // ------------------------------------------------------
        
        // 解除 expunged 状态 (unexpungeLocked)
        if e.unexpungeLocked() {
            // 这个 entry 被特殊标记了(expunged)
            // 如果之前是 expunged，意味着 dirty map 中没有这个 key。
            // 既然我们要复活这个 key，必须把它重新塞回 dirty map，保证数据一致性。
            m.dirty[key] = e
        }
        
        // 执行交换 (swapLocked)
        if v := e.swapLocked(&value); v != nil {
            loaded = true
            previous = *v
        }
    } else if e, ok := m.dirty[key]; ok {
        // ------------------------------------------------------
        // 分支 B：Key 仅在 Dirty Map 中
        // (Read 里没有，说明是之前新加的，还没提升)
        // ------------------------------------------------------
        
        // 直接交换
        if v := e.swapLocked(&value); v != nil {
            loaded = true
            previous = *v
        }
    } else {
        // ------------------------------------------------------
        // 分支 C：Key 完全不存在 (是全新的 Key)
        // ------------------------------------------------------
        
        // amended: Dirty Map 里是否有 Read Map 不知道的新数据？
        // amended = false: Read Map 包含了所有数据（或者 Dirty 是空的）
        // “放心大胆地查 Read 吧！如果 Read 里没找到，那就肯定没有，不用去 Dirty 找了，也不用加锁。”
        
        // amended = true: Read Map 已经过时了，Dirty Map 里藏着 Read 没有的新 Key
        // “Read 里没找到？别急着放弃！Dirty 里可能有，去加把锁查查 Dirty 吧。”
        if !read.amended {
            // 
            // 如果 amended 为 false，说明 dirty map 为空, 或者 read map包含了所有数据
            // 此时初始化 dirty map (把 read 里的数据拷过来)
            // 这是整个过程中最[重]的操作: 把 Read 里的数据拷贝到 Dirty 里
            m.dirtyLocked()
            // 拷贝完之后, 标记 read map 已经过时了
            m.read.Store(&readOnly{m: read.m, amended: true})
        }
        
        // 新增key
        m.dirty[key] = newEntry(value)
    }
    m.mu.Unlock()
    return previous, loaded
}

// 当dirty map为空的时候
// 将 readmap 所有数据拷贝道 dirty map
func (m *Map) dirtyLocked() {
    if m.dirty != nil {
        return
    }

    read := m.loadReadOnly()
    m.dirty = make(map[any]*entry, len(read.m))
    for k, e := range read.m {
        if !e.tryExpungeLocked() {
            m.dirty[k] = e
        }
    }
}

func (m *Map) Load(key any) (value any, ok bool) {
    read := m.loadReadOnly()
    e, ok := read.m[key]
    // 如果 Read 里没找到
    // amended = false: Read Map 包含了所有数据（或者 Dirty 是空的）
    // amended = true: Read Map 已经过时了，Dirty Map 里藏着 Read 没有的新 Key
    // 注意：如果 ok=false 但 amended=false，直接跳过下面的 if，返回 nil
    if !ok && read.amended {
        m.mu.Lock()
        // 阶段2: 加锁与双重检查 (Slow Path)
        // 关键】Double Check (双重检查)
        // 在我们排队等锁的时候，可能别人已经触发了“提升”，把 Dirty 变 Read 了。
        // 所以拿到锁之后,必须再获取一个 read
        read = m.loadReadOnly()
        e, ok = read.m[key]
        // 如果 Read 里还是没有，且 amended 依然是 true
        if !ok && read.amended {
            // 查 dirty map
            e, ok = m.dirty[key]
            // 标记miss的次数
            // 不管 Dirty 里有没有这个 Key，只要我们被迫锁了 mu 进来查 Dirty就算一次 Miss
            // 因为这代表 Read Map 已经覆盖不全了.
            m.missLocked()
        }
        m.mu.Unlock()
    }
    // 这是快路径
    if !ok {
        return nil, false
    }
    // 返回
    return e.load()
}

func (m *Map) missLocked() {
    m.misses++ // 1. 记过次数 +1
    
    // 2. 判断是否达到阈值
    if m.misses < len(m.dirty) {
        return // 还没到，忍了
    }
    
    // 3. 忍无可忍，触发提升！
    m.read.Store(&readOnly{m: m.dirty}) // Dirty 变 Read (默认 amended=false)
    m.dirty = nil                       // Dirty 清空
    m.misses = 0                        // 计数器归零
}