vmap

package module
v2.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: Apache-2.0 Imports: 10 Imported by: 11

README

vmap

Go

vmap 是一个并发安全、支持 TTL 的 any -> any 映射容器,专为「配置树 / 会话表 / JSON 友好的动态结构」设计。

在 sync.Map 之上补齐了它缺少的东西:嵌套子表、按 key 的过期回调、深拷贝、JSON 编组、与原生 map 的双向转换,同时保证所有回调都在锁外异步执行。

特性

  • 并发安全:内部 sync.RWMutex,所有导出方法可并发调用(*Map 指针语义,禁止按值复制)
  • TTL:登记时或读取时均可指定过期时间,支持到期/删除/关闭三种回调
  • 嵌套:值为 *Map 即可无限层组合,提供 GetNewMaps / IndexHas 链式访问
  • 深拷贝:Clone / Copy 复制嵌套子表、切片、结构体,并正确处理环引用
  • JSON 编组:实现 json.Marshaler / json.Unmarshaler,键名冲突自动消歧
  • 互操作:ReadAll / WriteTo / ReadFrom 在 *Map 与任意 map 之间转换,带溢出检查
  • 健壮性:深度上限、环引用检测、panic 回调观测、索引自愈

导入

import "github.com/456vv/vmap/v2" // package vmap

快速开始

m := vmap.NewMap()
m.Set("name", "gopher")
m.Set("age", 3)

fmt.Println(m.Get("name"))       // gopher
v, ok := m.GetHas("age")         // 3, true
fmt.Println(m.Len())             // 2

m.Del("age")
fmt.Println(m.Has("age"))        // false

// 不存在时返回默认值;键存在且值为 nil 时仍返回 nil
m.GetOrDefault("missing", "dft") // dft

API 概览

构造与生命周期
方法 说明
NewMap() 创建空表
NewMapSize(n int) 预分配约 n 个键
Reset() 静默清空(不触发回调),保留小容量,可继续使用
Close() 终态关闭:停表、释放结构、异步触发已登记回调;之后写入为 no-op
IsClosed() bool 是否已关闭
读写
方法 说明
Set(key, val any) 写入;键不可比较或含 NaN 时 panic
Get(key) any / GetHas(key) (any, bool) 读取;后者可区分「不存在」与「值为 nil」
Has(key) bool 键是否存在
GetOrDefault(key, def any) any 键不存在时返回 def
LoadOrStore(key, val any) (any, bool) 存在则返回已有值,否则写入
Del(key) / Dels(keys []any) 删除,触发已登记的过期回调
LoadAndDelete(key) (any, bool) 原子取出并删除
Len() int 元素个数(以 data 为准)
嵌套与链式访问
user := m.GetNewMap("user")      // 不存在则创建
user.Set("id", 1)

cfg := m.GetNewMaps("a", "b", "c") // 逐层读取或创建;空参数返回接收者本身
cfg.Set("deep", true)

v, ok := m.IndexHas("a", "b", "c", "deep") // true, true
方法 说明
New(key) *Map 删掉旧值后写入一个新的空子表
GetNewMap(key) *Map 读取子表,不存在或类型不符则创建
GetNewMaps(keys ...any) *Map 链式版本
Index(keys ...any) any / IndexHas(...) 逐层读取,中间节点必须是非 nil *Map
TTL
m.SetExpired("token", 10*time.Minute)

// 带回调:到期、到期前被 Del、Close 时都会调用 f
m.SetExpiredCall("session", 30*time.Second, func(v any) {
    log.Printf("session expired: %v", v)
})

d, ok := m.TTL("session") // 剩余时间,可能为负
  • d > 0 设置有效期;d == 0 取消过期且不调用回调;d < 0 立即过期并调用回调
  • 回调 f == nil 时保留旧回调
  • 回调统一在释放锁之后的独立 goroutine 中执行,且 panic 会被捕获转交 SetPanicHandler
  • 键不存在时 SetExpired* 直接忽略
遍历与快照
m.Range(func(k, v any) bool {
    fmt.Println(k, v)
    return true // 返回 false 提前终止
})

keys := m.Keys()     // 快照,不会随原表变化
values := m.Values() // 与 Keys 同序

Range / Keys / Values 均在读锁内取快照后释放锁再回调,因此回调中可以安全地写同一个表。

复制与克隆
dup := m.Clone()               // 深拷贝,nil 接收者返回 nil

dst := vmap.NewMap()
err := dst.Copy(src, false)    // over=false 时不覆盖已存在的键
  • 嵌套 *Map、[]any、[]*Map、map[string]any、map[any]any、结构体字段都会被深拷贝
  • 环引用通过 repl 映射复用已创建的副本,不会无限递归
  • TTL 一律复制;已过期但定时器尚未触发的键会立即过期,而不是退化成永久键
  • 克隆出的子表在提交后统一激活定时器,避免与用户锁形成 ABBA 死锁
JSON
b, _ := json.Marshal(m)        // 嵌套 *Map 展开为 JSON 对象

var m2 vmap.Map
err := json.Unmarshal(b, &m2)  // 要求 JSON 对象;null 会清空接收者

fmt.Println(m.String())        // 等价于 MarshalJSON 的文本

键名规则:string / 数值 / bool 直接字符串化;类型冲突时追加后缀,且后缀本身也会避让:

{"1": "string-key", "1#2(int)": "int-key"}
与原生 map 互操作
var raw map[string]any
err := m.WriteTo(&raw)         // *Map -> map,nil map 会自动 make

m2 := vmap.NewMap()
err = m2.ReadFrom(raw)         // map -> *Map,合并而非清空

all := m.ReadAll()             // 递归展开为 map[any]any

转换过程带类型与范围检查:整数溢出、负数转无符号、非有限浮点、含小数转整型、切片长度与数组不匹配等都会返回错误而不是静默截断。

可观测性
vmap.SetPanicHandler(func(r any) {
    log.Printf("vmap recovered panic: %v", r)
})

过期回调、快照、JSON 编组等路径中的用户代码 panic 都会被 recover 并转发到这里,避免打垮进程;传 nil 恢复静默。

语义与边界

场景 行为
键为切片 / map / 函数 / 含 NaN Set 系列 panic;Get 系列视为不存在
存入 *Map 保留引用
存入按值 Map 自动转为独立的 *Map 副本(含 TTL 快照)
存入原生 map / slice / struct 原样保存,Clone 时才深拷贝
Del 一个不存在的键 不触发回调
Close 之后 读取返回零值,写入静默忽略
Keys 顺序 插入序经交换删除扰动,不是严格有序
嵌套 / 编组 / 解析深度 上限 1024 层,超限返回错误或占位串
复制 Map 值 禁止,会复制锁并与源共享底层桶
回调执行时机 锁外异步,不保证顺序

并发模型与设计要点

  • 三表索引:data + keys + keyIndex 共同维护顺序与 O(1) 删除;三者长度不一致或下标错位时由 reindexLocked 自愈,读路径有兜底快照,写路径不为一致性付出全表扫描代价。
  • 交换删除:删除把末位键搬到空位,容量超过 64 且利用率低于 25% 时紧缩。
  • TTL 代次:每个过期登记带自增 gen,重新设置 TTL 后旧定时器即使触发也会被识别为过期代次而丢弃。
  • 锁外回调:所有 Del / 过期 / Close 的清理回调都先收集成 call,释放写锁后再异步执行。
  • 克隆两阶段:先在无锁状态下建好整张副本图(repl / made),提交后再逐个激活定时器,且只锁本次新建的表。
  • JSON 重入计数:MarshalJSON 用原子计数限制同一张表的未返回层数(上限 1024),配合 seen 集合截断环引用;嵌套错误被剥回同一个 errMarshalCycle。
  • 类型缓存:typeMayContainMap / typeHasMap / typeNeedsDeepCopy 三种类型查询共用 sync.Map 缓存,避免每次反射都重走类型树。

复杂度

操作 复杂度
Set / Get / Has / Del 均摊 O(1)
Len O(1)
Keys / Values / Range O(n)
Clone / Copy O(n)(按元素深度)
MarshalJSON O(n),仅在键名字符串冲突时排序

限制

  • 仅支持 *Map,按值使用会导致锁复制(go vet 的 copylocks 会报错)
  • 键必须可比较且不含 NaN,等价于 Go 原生 map 的键规则
  • 不保证键的稳定插入序
  • String() 返回的是 JSON 文本,不是调试格式

License

Apache-2.0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SetPanicHandler added in v2.4.0

func SetPanicHandler(fn func(any))

SetPanicHandler 设置过期回调 panic 的观测函数。fn 为 nil 时恢复静默。

Types

type Map

type Map struct {
	// contains filtered or unexported fields
}

Map 是带 TTL 的 key-value 映射。TTL 可以在登记时指定,也可以在读取时指定。 禁止按值复制 Map(会复制锁且与源共享底层桶,并发写是 fatal)。请使用 *Map。

func NewMap

func NewMap() *Map

NewMap 创建空 Map。

func NewMapSize added in v2.4.0

func NewMapSize(n int) *Map

NewMapSize 预分配约 n 个键。n<=0 与 NewMap 相同。

func (*Map) Clone added in v2.4.0

func (m *Map) Clone() *Map

Clone 深拷贝。nil 接收者返回 nil。

func (*Map) Close added in v2.4.0

func (m *Map) Close()

Close 终态关闭 Map。 停止所有定时器并在释放锁后异步触发已登记的有效清理回调。 彻底释放底层数据结构并置为已关闭状态。关闭后 Map 变为不可写入状态。

func (*Map) Copy

func (m *Map) Copy(from *Map, over bool) error

Copy 把 from 写入接收者。over 为 false 时不覆盖已存在的键。 nil、自拷贝直接返回。嵌套 *Map 和容器会深拷贝。 TTL 一律复制;deadline 已过但源定时器还没跑的键会马上过期,而不是变成永久键。

func (*Map) Del

func (m *Map) Del(key any)

Del 删除。过期回调在释放锁之后、另一个 goroutine 里执行。

func (*Map) Dels

func (m *Map) Dels(keys []any)

Dels 一次加锁删除。

func (*Map) Get

func (m *Map) Get(key any) any

Get 读取。不存在返回 nil,无法与存入的 nil 区分,请用 GetHas。

func (*Map) GetHas

func (m *Map) GetHas(key any) (any, bool)

GetHas 读取并判断。

func (*Map) GetNewMap

func (m *Map) GetNewMap(key any) *Map

GetNewMap 读取 key 对应的 *Map;不存在时创建。

func (*Map) GetNewMaps

func (m *Map) GetNewMaps(keys ...any) *Map

GetNewMaps 链式读取或创建。空参数返回接收者本身。

func (*Map) GetOrDefault

func (m *Map) GetOrDefault(key any, def any) any

GetOrDefault 键不存在时返回 def。键存在且值为 nil 时返回 nil。

func (*Map) Has

func (m *Map) Has(key any) bool

Has 判断键是否存在。与 GetHas 看同一份 data。

func (*Map) Index

func (m *Map) Index(key ...any) any

Index 指定读取。

func (*Map) IndexHas

func (m *Map) IndexHas(keys ...any) (any, bool)

IndexHas 逐层读取。中间节点必须是非 nil *Map。

m1 := vmap.NewMap()
m2 := vmap.NewMap()
m2.Set("b", "value")
m1.Set("a", m2)
v, ok := m1.IndexHas("a", "b")

func (*Map) IsClosed added in v2.4.0

func (m *Map) IsClosed() bool

IsClosed 返回 Map 是否已被终态关闭。

func (*Map) Keys added in v2.3.0

func (m *Map) Keys() []any

Keys 返回键快照。删除仍是交换删除,不是严格插入序。

func (*Map) Len

func (m *Map) Len() int

Len 长度。以 len(data) 为准,不再单独维护会漂移的 length。

func (*Map) LoadAndDelete added in v2.4.0

func (m *Map) LoadAndDelete(key any) (any, bool)

LoadAndDelete 原子取出并删除。

func (*Map) LoadOrStore added in v2.4.0

func (m *Map) LoadOrStore(key, val any) (actual any, loaded bool)

LoadOrStore 键已存在则返回已有值,否则写入 val。

func (*Map) MarshalJSON

func (m *Map) MarshalJSON() ([]byte, error)

MarshalJSON 转 JSON。只有键字符串冲突时才追加后缀,并保证后缀本身也不冲突。 encoding/json 会排序对象键,输出不依赖 map 遍历顺序。

func (*Map) New

func (m *Map) New(key any) *Map

New 删除 key(若存在)后写入一个新 Map。

func (*Map) Range

func (m *Map) Range(f func(key, value any) bool)

Range 把快照交给 f。f 返回 false 时停止。

func (*Map) ReadAll

func (m *Map) ReadAll() any

ReadAll 递归展开为 map[any]any。环引用写成占位字符串,避免栈溢出。不复制 TTL。 []*Map 保持原类型,避免旧的类型断言失效;[]any 会继续展开。

func (*Map) ReadFrom

func (m *Map) ReadFrom(mm any) (err error)

ReadFrom 从 map 合并到当前 Map,不先清空。需要替换时先 Reset。

func (*Map) Reset

func (m *Map) Reset()

Reset 静默清空所有键并停止定时器,不触发任何回调。 复用内部切片容量(不超过 shrinkMinCap),调用后 Map 仍处于可用状态。

func (*Map) Set

func (m *Map) Set(key, val any)

Set 设置

func (*Map) SetExpired

func (m *Map) SetExpired(key any, d time.Duration)

SetExpired 设置有效期。d==0 取消;键不存在则忽略。

func (*Map) SetExpiredCall

func (m *Map) SetExpiredCall(key any, d time.Duration, f func(any))

SetExpiredCall 设置有效期。过期、到期前 Del、Close 时调用 f。 d==0 取消且不调用 f。d<0 立即过期并调用 f。f==nil 时保留旧回调。

func (*Map) String

func (m *Map) String() (s string)

String JSON 文本。nil 接收者为 "null"。失败时返回带错误的占位串,而不是空串。

func (*Map) TTL added in v2.4.0

func (m *Map) TTL(key any) (time.Duration, bool)

TTL 返回剩余有效期。ok 为 false 表示没有设置过期。剩余时间可能为负。

func (*Map) UnmarshalJSON

func (m *Map) UnmarshalJSON(data []byte) error

UnmarshalJSON 要求 JSON 对象。null 会清空。解析失败不修改接收者。

func (*Map) Values added in v2.3.0

func (m *Map) Values() []any

Values 按 Keys 的同一顺序返回值快照。

func (*Map) WriteTo

func (m *Map) WriteTo(mm any) (err error)

WriteTo 把内容写入 mm。mm 必须是 map,或指向 map 的指针。 nil map 且可设置时会自动 make。接口元素里的 *Map 仍写成 map[any]any。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL