diff --git a/common/utils/emap.go b/common/utils/emap.go index b3994bf9..acbd83a0 100644 --- a/common/utils/emap.go +++ b/common/utils/emap.go @@ -6,55 +6,51 @@ import ( "sync" ) -// 泛型有序Map的实现，结合了SliceMap的并发安全和orderedMap的有序性及高效查找 - -// MapEntry 表示Map中的一个键值对条目 +// MapEntry 表示有序Map中的单个键值对条目，维护双向链表和哈希冲突链表指针 type MapEntry[K comparable, V any] struct { key K value V - // 用于维护插入顺序的双向链表指针 + // 双向链表指针：维护键值对的插入顺序 prev, next *MapEntry[K, V] - // 用于哈希表碰撞处理的链表指针 + // 哈希冲突链表指针：处理哈希表中相同哈希值的键 hashNext *MapEntry[K, V] - // 标记是否被删除 + // deleted 标记条目是否被逻辑删除（避免直接删除链表节点导致遍历断裂） deleted bool } -// OrderedMap 是一个泛型的有序Map实现 +// OrderedMap 泛型有序Map实现，支持按插入顺序遍历、并发安全，且修复Range期间添加阻塞问题 type OrderedMap[K comparable, V any] struct { - mu sync.RWMutex // 并发安全锁 - hash *maphash.Hash // 哈希计算器 - hashTable map[uint64]*MapEntry[K, V] // 哈希表，用于快速查找 - first *MapEntry[K, V] // 双向链表头，维护插入顺序 - last *MapEntry[K, V] // 双向链表尾，维护插入顺序 - size int // 当前元素数量（排除已删除的） + mu sync.RWMutex // 读写锁：保证并发安全，读多写少场景更高效 + hash *maphash.Hash // 哈希计算器：为键生成哈希值用于快速查找 + hashTable map[uint64]*MapEntry[K, V] // 哈希表：存储哈希值到对应冲突链表头的映射 + first *MapEntry[K, V] // 双向链表头：指向第一个插入的有效条目 + last *MapEntry[K, V] // 双向链表尾：指向最后一个插入的有效条目 + size int // 有效条目数量：排除已逻辑删除的条目 } -// NewOrderedMap 创建一个新的泛型有序Map +// NewOrderedMap 创建一个新的泛型有序Map实例 func NewOrderedMap[K comparable, V any]() *OrderedMap[K, V] { return &OrderedMap[K, V]{ - hash: &maphash.Hash{}, - + hash: &maphash.Hash{}, hashTable: make(map[uint64]*MapEntry[K, V]), } } -// 计算键的哈希值 +// hashKey 为指定键生成哈希值（内部方法，需在外层加锁保证并发安全） +// 注：复杂类型需自定义序列化逻辑，此处简化为通过fmt.Sprintf转为字符串后计算哈希 func (m *OrderedMap[K, V]) hashKey(key K) uint64 { - // 这里简化实现，实际使用中可能需要根据K的类型做特殊处理 - // 对于基本类型可以直接写入，复杂类型可能需要序列化 m.hash.Reset() - // 注意：实际使用时需要根据K的具体类型实现正确的哈希计算 - // 这里只是示例，可能需要调整 m.hash.WriteString(fmt.Sprintf("%v", key)) return m.hash.Sum64() } -// 查找键对应的条目 -func (m *OrderedMap[K, V]) lookup(key K) (hash uint64, entry, prevEntry *MapEntry[K, V]) { +// lookup 查找指定键对应的条目、其哈希值及哈希冲突链表中的前驱条目（内部方法，需外层加锁） +// 返回值：哈希值、目标条目（未找到或已删除则为nil）、哈希冲突链表中的前驱条目 +func (m *OrderedMap[K, V]) lookup(key K) (hash uint64, entry, prevHashEntry *MapEntry[K, V]) { hash = m.hashKey(key) - for entry = m.hashTable[hash]; entry != nil; prevEntry, entry = entry, entry.hashNext { + // 遍历哈希冲突链表，查找未删除的目标键 + for entry = m.hashTable[hash]; entry != nil; prevHashEntry, entry = entry, entry.hashNext { if !entry.deleted && entry.key == key { break } @@ -62,16 +58,17 @@ func (m *OrderedMap[K, V]) lookup(key K) (hash uint64, entry, prevEntry *MapEntr return } -// Store 存储键值对，如果键已存在则更新值 +// Store 存储键值对：键存在则更新值，键不存在则新增（按插入顺序追加到链表末尾） func (m *OrderedMap[K, V]) Store(key K, value V) { m.mu.Lock() defer m.mu.Unlock() - hash, entry, prevEntry := m.lookup(key) + hash, entry, prevHashEntry := m.lookup(key) + // 情况1：键已存在（且未删除），直接更新值 if entry != nil { - // 键已存在，更新值并确保标记为未删除 entry.value = value + // 若条目曾被逻辑删除，恢复为有效状态并更新计数 if entry.deleted { entry.deleted = false m.size++ @@ -79,73 +76,80 @@ func (m *OrderedMap[K, V]) Store(key K, value V) { return } - // 创建新条目 + // 情况2：键不存在，创建新条目 entry = &MapEntry[K, V]{ key: key, value: value, } - // 添加到哈希表 - if prevEntry == nil { + // 2.1 将新条目添加到哈希冲突链表（处理哈希碰撞） + if prevHashEntry == nil { + // 哈希桶为空，直接作为桶的头节点 m.hashTable[hash] = entry } else { - prevEntry.hashNext = entry + // 哈希桶已有节点，追加到冲突链表末尾 + prevHashEntry.hashNext = entry } - // 添加到双向链表末尾以保持插入顺序 + // 2.2 将新条目添加到双向链表末尾（保证插入顺序） if m.last != nil { + // 链表已有节点，更新尾节点指针 entry.prev = m.last m.last.next = entry } else { - // 第一个元素 + // 链表为空，新条目同时作为头节点 m.first = entry } + // 更新尾节点为新条目 m.last = entry + // 增加有效条目计数 m.size++ } -// Load 查找并返回键对应的值，如果不存在则返回零值和false +// Load 查找指定键的值：存在则返回值和true，不存在则返回对应类型零值和false func (m *OrderedMap[K, V]) Load(key K) (value V, exists bool) { m.mu.RLock() defer m.mu.RUnlock() _, entry, _ := m.lookup(key) + // 仅当条目存在且未删除时，返回有效数据 if entry != nil && !entry.deleted { return entry.value, true } return value, false } -// LoadOrStore 查找并返回键对应的值，如果不存在则存储并返回给定值 +// LoadOrStore 查找并返回键对应的值：存在则返回原值和true，不存在则存储并返回新值和false func (m *OrderedMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool) { m.mu.Lock() defer m.mu.Unlock() _, entry, _ := m.lookup(key) + // 情况1：键已存在（未删除），返回原值 if entry != nil && !entry.deleted { return entry.value, true } - // 执行存储操作 + // 情况2：键不存在，执行存储逻辑 hash := m.hashKey(key) entry = &MapEntry[K, V]{ key: key, value: value, } - // 添加到哈希表 + // 2.1 处理哈希冲突，添加到对应哈希桶 if m.hashTable[hash] == nil { m.hashTable[hash] = entry } else { - // 处理哈希冲突 - last := m.hashTable[hash] - for last.hashNext != nil { - last = last.hashNext + // 遍历冲突链表到末尾，追加新条目 + lastHashEntry := m.hashTable[hash] + for lastHashEntry.hashNext != nil { + lastHashEntry = lastHashEntry.hashNext } - last.hashNext = entry + lastHashEntry.hashNext = entry } - // 添加到双向链表 + // 2.2 添加到双向链表末尾，保证插入顺序 if m.last != nil { entry.prev = m.last m.last.next = entry @@ -155,51 +159,61 @@ func (m *OrderedMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool) { m.last = entry m.size++ + // 返回存储的新值和“未加载（新存储）”标记 return value, false } -// Delete 标记删除指定的键 +// Delete 逻辑删除指定键：仅标记deleted为true，不直接删除节点（避免遍历链表断裂） func (m *OrderedMap[K, V]) Delete(key K) { m.mu.Lock() defer m.mu.Unlock() _, entry, _ := m.lookup(key) + // 仅当条目存在且未删除时，执行逻辑删除并更新计数 if entry != nil && !entry.deleted { entry.deleted = true m.size-- } } -// Range 按插入顺序迭代Map中的所有键值对 -// 如果f返回false，则停止迭代 +// Range 按插入顺序遍历所有有效键值对：修复后支持遍历期间添加，新添加条目不影响当前遍历 +// 回调函数f返回false时，停止遍历 func (m *OrderedMap[K, V]) Range(f func(key K, value V) bool) { + // 第一步：加读锁复制快照（仅持有极短时间，避免阻塞写操作） m.mu.RLock() - defer m.mu.RUnlock() - + // 预分配切片容量（等于有效条目数），减少动态扩容开销 + snapshot := make([]*MapEntry[K, V], 0, m.size) current := m.first + // 遍历双向链表，收集所有未删除的有效条目 for current != nil { if !current.deleted { - if !f(current.key, current.value) { - return - } + snapshot = append(snapshot, current) } current = current.next } + // 关键：复制完成后立即释放读锁，允许Store等写操作执行 + m.mu.RUnlock() + + // 第二步：遍历快照切片，执行用户回调（无锁状态，安全且高效） + for _, entry := range snapshot { + if !f(entry.key, entry.value) { + return // 回调返回false，终止遍历 + } + } } -// Len 返回当前Map中的元素数量（排除已删除的） +// Len 返回当前Map中的有效条目数量（排除已逻辑删除的条目） func (m *OrderedMap[K, V]) Len() int { m.mu.RLock() defer m.mu.RUnlock() return m.size } -// Clear 清空Map中的所有元素 +// Clear 清空Map所有内容：重置哈希表、双向链表和计数（物理清空，而非逻辑删除） func (m *OrderedMap[K, V]) Clear() { m.mu.Lock() defer m.mu.Unlock() - // 重置所有指针和计数器 m.first = nil m.last = nil m.hashTable = make(map[uint64]*MapEntry[K, V])