├── .github └── workflows │ └── release.yml ├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── README.zh.md ├── cachemap ├── cache_map.go └── cache_map_test.go ├── go.mod ├── go.sum ├── internal └── utils │ ├── zero.go │ └── zero_test.go ├── mutex_map.go └── mutex_map_test.go /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: create-release 2 | 3 | on: 4 | push: 5 | branches: 6 | - main # 监听 main 分支的 push 操作（编译和测试/代码检查） 7 | tags: 8 | - 'v*' # 监听以 'v' 开头的标签的 push 操作（发布 Release） 9 | 10 | jobs: 11 | lint: 12 | name: lint 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/setup-go@v5 16 | with: 17 | go-version: "1.23.x" 18 | - uses: actions/checkout@v4 19 | - name: golangci-lint 20 | uses: golangci/golangci-lint-action@v6 21 | with: 22 | version: latest 23 | 24 | test: 25 | runs-on: ubuntu-latest 26 | strategy: 27 | matrix: 28 | go: [ "1.22.x", "1.23.x" ] 29 | steps: 30 | - uses: actions/checkout@v4 31 | 32 | - uses: actions/setup-go@v5 33 | with: 34 | go-version: ${{ matrix.go }} 35 | 36 | - name: Run test 37 | run: make test COVERAGE_DIR=/tmp/coverage 38 | 39 | - name: Send goveralls coverage 40 | uses: shogo82148/actions-goveralls@v1 41 | with: 42 | path-to-profile: /tmp/coverage/combined.txt 43 | flag-name: Go-${{ matrix.go }} 44 | parallel: true 45 | if: ${{ github.event.repository.fork == false }} # 仅在非 fork 时上传覆盖率 46 | 47 | check-coverage: 48 | name: Check coverage 49 | needs: [ test ] 50 | runs-on: ubuntu-latest 51 | steps: 52 | - uses: shogo82148/actions-goveralls@v1 53 | with: 54 | parallel-finished: true 55 | if: ${{ github.event.repository.fork == false }} # 仅在非 fork 时检查覆盖率 56 | 57 | # 发布 Release 58 | release: 59 | name: Release a new version 60 | needs: [ lint, test ] 61 | runs-on: ubuntu-latest 62 | # 仅在推送标签时执行 - && - 仅在非 fork 时执行发布 63 | if: ${{ github.event.repository.fork == false && success() && startsWith(github.ref, 'refs/tags/v') }} 64 | steps: 65 | # 1. 检出代码 66 | - name: Checkout code 67 | uses: actions/checkout@v4 68 | 69 | # 2. 创建 Release 和上传源码包 70 | - name: Create Release 71 | uses: softprops/action-gh-release@v2 72 | with: 73 | generate_release_notes: true 74 | env: 75 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 76 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # If you prefer the allow list template instead of the deny list, see community template: 2 | # https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore 3 | # 4 | # Binaries for programs and plugins 5 | *.exe 6 | *.exe~ 7 | *.dll 8 | *.so 9 | *.dylib 10 | 11 | # Test binary, built with `go test -c` 12 | *.test 13 | 14 | # Output of the go coverage tool, specifically when used with LiteIDE 15 | *.out 16 | 17 | # Dependency directories (remove the comment below to include it) 18 | # vendor/ 19 | 20 | # Go workspace file 21 | go.work 22 | go.work.sum 23 | 24 | # env file 25 | .env 26 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 yangyile-yyle88 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | COVERAGE_DIR ?= .coverage 2 | 3 | # cp from: https://github.com/yyle88/syncmap/blob/5ad6d0d6a16cbef3f4b5c5d5e6b56b46cb55a16a/Makefile#L4 4 | test: 5 | @-rm -r $(COVERAGE_DIR) 6 | @mkdir $(COVERAGE_DIR) 7 | make test-with-flags TEST_FLAGS='-v -race -covermode atomic -coverprofile $$(COVERAGE_DIR)/combined.txt -bench=. -benchmem -timeout 20m' 8 | 9 | test-with-flags: 10 | @go test $(TEST_FLAGS) ./... 11 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/yyle88/mutexmap/release.yml?branch=main&label=BUILD)](https://github.com/yyle88/mutexmap/actions/workflows/release.yml?query=branch%3Amain) 2 | [![GoDoc](https://pkg.go.dev/badge/github.com/yyle88/mutexmap)](https://pkg.go.dev/github.com/yyle88/mutexmap) 3 | [![Coverage Status](https://img.shields.io/coveralls/github/yyle88/mutexmap/master.svg)](https://coveralls.io/github/yyle88/mutexmap?branch=main) 4 | ![Supported Go Versions](https://img.shields.io/badge/Go-1.22%2C%201.23-lightgrey.svg) 5 | [![GitHub Release](https://img.shields.io/github/release/yyle88/mutexmap.svg)](https://github.com/yyle88/mutexmap/releases) 6 | [![Go Report Card](https://goreportcard.com/badge/github.com/yyle88/mutexmap)](https://goreportcard.com/report/github.com/yyle88/mutexmap) 7 | 8 | # MutexMap - A Thread-Safe Map for Go 9 | 10 | A thread-safe map implementation for Go, using `sync.RWMutex` to synchronize access. This package is optimized for scenarios involving concurrent reads and writes, providing efficient and reliable operations for multi-thread applications. 11 | 12 | ## README 13 | 14 | [中文说明](README.zh.md) 15 | 16 | ## Overview 17 | 18 | Go’s standard `map` is not safe for concurrent access. This package wraps a `map[K]V` with `sync.RWMutex` to provide thread safety. With `RWMutex`, multiple readers can access the map simultaneously, while writes are synchronized to prevent race conditions. 19 | 20 | Key highlights: 21 | - **Thread-safety**: Prevents data races in concurrent environments. 22 | - **Efficient Reads**: Read operations (`Get`, `Range`) are lock-free for other readers. 23 | - **Synchronous Write**: Write operations (`Set`, `Delete`, `Getset`) are synchronous. 24 | 25 | This package is suitable for use cases requiring frequent reads and occasional writes with a shared map. 26 | 27 | ## Installation 28 | 29 | ```bash 30 | go get github.com/yyle88/mutexmap 31 | ``` 32 | 33 | ## Example Usage 34 | 35 | ### Basic Operations 36 | 37 | ```go 38 | package main 39 | 40 | import ( 41 | "fmt" 42 | "github.com/yyle88/mutexmap" 43 | ) 44 | 45 | func main() { 46 | mp := mutexmap.NewMap 47 | 48 | mp.Set("key1", 100) 49 | mp.Set("key2", 200) 50 | 51 | if value, found := mp.Get("key1"); found { 52 | fmt.Println("Key1 Value:", value) 53 | } 54 | 55 | mp.Range(func(key string, value int) bool { 56 | fmt.Println(key, value) 57 | return true 58 | }) 59 | } 60 | ``` 61 | 62 | ### Using `Getset` for Cached Initialization 63 | 64 | ```go 65 | package main 66 | 67 | import ( 68 | "fmt" 69 | "github.com/yyle88/mutexmap" 70 | ) 71 | 72 | func main() { 73 | mp := mutexmap.NewMap 74 | 75 | value, created := mp.Getset("exampleKey", func() string { 76 | return "This is a computed value" 77 | }) 78 | fmt.Println("Created:", created, "Value:", value) 79 | 80 | value, created = mp.Getset("exampleKey", func() string { 81 | return "Another computed value" 82 | }) 83 | fmt.Println("Created:", created, "Value:", value) 84 | } 85 | ``` 86 | 87 | ## Features 88 | 89 | - **Concurrent Access**: Allows multiple goroutines to safely read and write to the map. 90 | - **Optimized Reads**: Supports simultaneous reads for better performance. 91 | - **Custom Initialization**: Use `Getset` to initialize values only if they don’t already exist. 92 | 93 | --- 94 | 95 | ## Method Summary 96 | 97 | | Method | Description | 98 | |----------------------------------------|--------------------------------------------------------------------------------------------------| 99 | | `NewMap[K comparable, V any](cap int)` | Creates a new `Map` with an optional initial capacity. | 100 | | `Get(k K) (V, bool)` | Retrieves the value for the given key. Returns `false` if the key is not found. | 101 | | `Set(k K, v V)` | Sets a value for the given key. Overwrites if the key already exists. | 102 | | `Delete(k K)` | Removes the key-value pair from the map. | 103 | | `Len() int` | Returns the number of elements in the map. | 104 | | `Range(func(k K, v V) bool)` | Iterates over all key-value pairs. Stops if the callback returns `false`. | 105 | | `Getset(k K, func() V) (V, bool)` | Gets a value or creates it if it doesn’t exist, ensuring the creation is atomic and thread-safe. | 106 | 107 | --- 108 | 109 | ## Why Use MutexMap? 110 | 111 | 1. **Thread Safety**: Essential for shared maps in multi-threaded environments. 112 | 2. **Efficient Reads**: Read lock (`RLock`) ensures non-blocking reads for other readers. 113 | 3. **Write Synchronization**: Write lock (`Lock`) ensures data integrity during modifications. 114 | 4. **Flexible Initialization**: The `Getset` method prevents redundant computations. 115 | 116 | --- 117 | 118 | ## License 119 | 120 | `mutexmap` is open-source and released under the MIT License. See the [LICENSE](LICENSE) file for more information. 121 | 122 | --- 123 | 124 | ## Support 125 | 126 | Welcome to contribute to this project by submitting pull requests or reporting issues. 127 | 128 | If you find this package helpful, give it a star on GitHub! 129 | 130 | **Thank you for your support!** 131 | 132 | **Happy Coding with `mutexmap`!** 🎉 133 | 134 | Give me stars. Thank you!!! 135 | 136 | ## GitHub Stars 137 | 138 | [![starring](https://starchart.cc/yyle88/mutexmap.svg?variant=adaptive)](https://starchart.cc/yyle88/mutexmap) 139 | -------------------------------------------------------------------------------- /README.zh.md: -------------------------------------------------------------------------------- 1 | # MutexMap - 基于 Mutex 实现的线程安全 Map 2 | 3 | MutexMap 是一个基于 `sync.RWMutex` 和标准 `map[K]V` 的线程安全实现，专为需要高效并发读写的场景设计。通过 `RWMutex` 实现读写锁，支持多线程安全访问，适合多协程环境下的共享数据操作。 4 | 5 | ## 目录 6 | 7 | [ENGLISH README](README.md) 8 | 9 | --- 10 | 11 | ## 项目概览 12 | 13 | Go 标准库的 `map` 在并发访问场景下并不安全。本库对 `map[K]V` 进行了封装，借助 `sync.RWMutex` 提供线程安全性，支持高效的并发操作。 14 | 15 | ### 核心特点 16 | 17 | - **线程安全**：通过读写锁避免数据竞争。 18 | - **高效读操作**：允许多个读操作同时进行，不互相阻塞。 19 | - **同步写操作**：使用写锁控制写操作，确保数据一致性。 20 | 21 | ### 适用场景 22 | 23 | 适合以下需求的应用场景： 24 | - 需要共享存储的数据结构。 25 | - 多读少写的并发访问场景。 26 | - 需要通过函数安全初始化值的场景（`Getset` 方法）。 27 | 28 | --- 29 | 30 | ## 安装 31 | 32 | 使用 `go get` 安装本库： 33 | 34 | ```bash 35 | go get github.com/yyle88/mutexmap 36 | ``` 37 | 38 | --- 39 | 40 | ## 示例代码 41 | 42 | ### 基础操作示例 43 | 44 | ```go 45 | package main 46 | 47 | import ( 48 | "fmt" 49 | "github.com/yyle88/mutexmap" 50 | ) 51 | 52 | func main() { 53 | mp := mutexmap.NewMap.Set("key1", 100) 54 | mp.Set("key2", 200) 55 | 56 | // 获取值 57 | if value, found := mp.Get("key1"); found { 58 | fmt.Println("Key1 的值:", value) 59 | } else { 60 | fmt.Println("Key1 不存在") 61 | } 62 | 63 | // 遍历所有键值对 64 | mp.Range(func(key string, value int) bool { 65 | fmt.Println(key, value) 66 | return true 67 | }) 68 | } 69 | ``` 70 | 71 | ### 使用 `Getset` 方法实现值的缓存初始化 72 | 73 | ```go 74 | package main 75 | 76 | import ( 77 | "fmt" 78 | "github.com/yyle88/mutexmap" 79 | ) 80 | 81 | func main() { 82 | mp := mutexmap.NewMap 83 | 84 | // 如果键不存在，则, created := mp.Getset("exampleKey", func() string { 85 | return "这是一段计算得到的值" 86 | }) 87 | fmt.Println("值是否新创建:", created, "值:", value) 88 | 89 | // 再次调用 Getset 方法，值不会被重新创建 90 | value, created = mp.Getset("exampleKey", func() string { 91 | return "这段值不会被创建" 92 | }) 93 | fmt.Println("值是否新创建:", created, "值:", value) 94 | } 95 | ``` 96 | 97 | --- 98 | 99 | ## 功能概览 100 | 101 | ### 方法一览 102 | 103 | | 方法 | 描述 | 104 | |----------------------------------------|-----------------------------------------------| 105 | | `NewMap[K comparable, V any](cap int)` | 创建一个新的线程安全 Map，支持设置初始容量。 | 106 | | `Get(k K) (V, bool)` | 获取指定键的值，如果键不存在，返回 `false`。 | 107 | | `Set(k K, v V)` | 设置指定键的值，如果键已存在则覆盖旧值。 | 108 | | `Delete(k K)` | 删除指定键的键值对。 | 109 | | `Len() int` | 返回当前 Map 中的键值对数量。 | 110 | | `Range(func(k K, v V) bool)` | 遍历所有键值对，并对每个键值对执行传入的回调函数。如果回调返回 `false`，终止遍历。 | 111 | | `Getset(k K, func() V) (V, bool)` | 获取指定键的值。如果键不存在，使用回调函数计算值并存储，返回值和是否新创建的标志。 | 112 | 113 | --- 114 | 115 | ## MutexMap 的优势 116 | 117 | 1. **线程安全** 118 | 借助读写锁实现线程安全，避免并发操作导致的数据竞争问题。 119 | 120 | 2. **高效的读操作** 121 | 使用读锁 (`RLock`) 支持多个读操作同时进行，提升并发性能。 122 | 123 | 3. **写操作的完整性** 124 | 写锁 (`Lock`) 确保写操作的同步性，防止数据不一致。 125 | 126 | 4. **灵活的值初始化** 127 | `Getset` 方法确保每个键的值只被安全创建一次，避免重复计算或初始化。 128 | 129 | --- 130 | 131 | ## 许可 132 | 133 | `mutexmap` 是一个开源项目，发布于 MIT 许可证下。有关更多信息，请参阅 [LICENSE](LICENSE) 文件。 134 | 135 | ## 贡献与支持 136 | 137 | 欢迎通过提交 pull request 或报告问题来贡献此项目。 138 | 139 | 如果你觉得这个包对你有帮助，请在 GitHub 上给个 ⭐，感谢支持！！！ 140 | 141 | **感谢你的支持！** 142 | 143 | **祝编程愉快！** 🎉 144 | 145 | Give me stars. Thank you!!! 146 | -------------------------------------------------------------------------------- /cachemap/cache_map.go: -------------------------------------------------------------------------------- 1 | package cachemap 2 | 3 | import ( 4 | "sync" 5 | 6 | "github.com/pkg/errors" 7 | "github.com/yyle88/mutexmap/internal/utils" 8 | ) 9 | 10 | type Map[K comparable, V any] struct { 11 | mp map[K]*valueBottle[V] 12 | mutex *sync.RWMutex 13 | } 14 | 15 | // New creates a new thread-safe map. 16 | // New 创建一个线程安全 map。 17 | func New[K comparable, V any]() *Map[K, V] { 18 | return NewMap[K, V](8) 19 | } 20 | 21 | type valueBottle[V any] struct { 22 | mutex *sync.RWMutex 23 | done bool //这里的done仅仅表示已经执行过，而不表示结果成功，有可能结果是失败的，但也标记为"done" 24 | res V 25 | err error //即使是计算错误，也保存下来，再次遇到时直接返回错误 26 | } 27 | 28 | // NewMap creates a new thread-safe map. 29 | // NewMap 创建一个线程安全 map。 30 | func NewMap[K comparable, V any](cap int) *Map[K, V] { 31 | return &Map[K, V]{ 32 | mp: make(map[K]*valueBottle[V], cap), 33 | mutex: &sync.RWMutex{}, 34 | } 35 | } 36 | 37 | // Get retrieves a value by key, returning the value, error, and whether it was computed. 38 | // Get 根据键获取值，返回值、错误以及是否已计算的状态。 39 | func (a *Map[K, V]) Get(k K) (res V, err error, done bool) { 40 | a.mutex.RLock() //首先用读锁去试探性的读数据 41 | defer a.mutex.RUnlock() 42 | vx, ok := a.mp[k] 43 | if !ok { 44 | return res, errors.New("not exist"), false 45 | } 46 | if !vx.done { 47 | return res, errors.New("not acted"), false 48 | } 49 | return vx.res, vx.err, true 50 | } 51 | 52 | // Set stores a value for a key with no associated error. 53 | // Set 为键存储一个值，不带错误信息。 54 | func (a *Map[K, V]) Set(k K, v V) { 55 | a.SetVe(k, v, nil) 56 | } 57 | 58 | // SetKv stores a value for a key with no associated error (alias for Set). 59 | // SetKv 为键存储一个值，不带错误信息（Set 的别名）。 60 | func (a *Map[K, V]) SetKv(k K, v V) { 61 | a.SetVe(k, v, nil) 62 | } 63 | 64 | // SetKe stores an error for a key with a zero value. 65 | // SetKe 为键存储一个错误，使用零值作为值。 66 | func (a *Map[K, V]) SetKe(k K, err error) { 67 | a.SetVe(k, utils.Zero[V](), err) 68 | } 69 | 70 | // SetVe stores a value and an optional error for a key, overwriting any existing item. 71 | // SetVe 为键存储值和可选错误，覆盖现有条目。 72 | func (a *Map[K, V]) SetVe(k K, v V, err error) { 73 | a.mutex.Lock() 74 | defer a.mutex.Unlock() 75 | a.mp[k] = &valueBottle[V]{ 76 | mutex: &sync.RWMutex{}, //其实当设置done以后就不会再用锁啦，但没有关系的，依然写在这里避免疑惑和出错 77 | done: true, 78 | res: v, 79 | err: err, 80 | } 81 | } 82 | 83 | // Getset retrieves a value by key or computes it using newValue if it doesn't exist, caching the result. 84 | // Getset 根据键获取值，若不存在则使用 newValue 计算并缓存结果。 85 | // Getset get a value, if value is not exist, then create an object and set into map. 86 | // when not exist, call the newValue to create new value and put it in to map as cache. 87 | // not lock all the map during call newValue even newValue is very slow and waste time. 88 | // so when already exist do not change the value, return the old value. 89 | // Orz means "or" but "or" is too ugly, more ugly than ugly. So I use Orz instead of it. 90 | func (a *Map[K, V]) Getset(k K, newValue func() (V, error)) (V, error) { 91 | if res, err, done := a.Get(k); done { 92 | return res, err 93 | } 94 | //在写锁内执行-因此在占用前有可能会执行别的操作-比如设置新值/删除值-设计时要考虑时序问题 95 | vb, mu := a.setBottle(k) 96 | //释放mp的写锁-因此在释放后有可能会执行别的操作-比如设置新值/删除值-设计时要考虑时序问题 97 | if mu != nil { 98 | defer mu.Unlock() 99 | 100 | func() { 101 | defer func() { 102 | if ove := recover(); ove != nil { 103 | if erp, ok := ove.(error); ok { 104 | vb.err = erp 105 | } else { 106 | vb.err = errors.Errorf("panic occurred. reason: %v", ove) 107 | } 108 | } 109 | }() 110 | vb.res, vb.err = newValue() //接着去计算数据，最终释放壳子的写锁，确保一个资源只被计算一次 111 | }() 112 | vb.done = true 113 | return vb.res, vb.err 114 | } else { 115 | if vb.done { 116 | return vb.res, vb.err 117 | } else { 118 | vb.mutex.RLock() //抢占壳子的读锁，当能抢到的时候说明壳子已经有数据，抢不到说明还没计算完 119 | defer vb.mutex.RUnlock() 120 | //当抢到读锁时，说明前面的执行已经完成（done），结果已经被赋值到壳子里，就可以使用和返回 121 | return vb.res, vb.err 122 | } 123 | } 124 | } 125 | 126 | // setBottle creates or retrieves a valueBottle for a key, returning the bottle and its mutex if new. 127 | // setBottle 为键创建或获取一个 valueBottle，若为新创建则返回 bottle 及其互斥锁。 128 | func (a *Map[K, V]) setBottle(k K) (*valueBottle[V], *sync.RWMutex) { 129 | a.mutex.Lock() //假如读不到数据再用写锁锁住，再去尝试读数据，假如确定还是读不到，就创建数据 130 | defer a.mutex.Unlock() //把最外面的大锁给释放掉，这把大锁的作用是避免重复创建空壳 131 | 132 | vx, exist := a.mp[k] 133 | if !exist { 134 | vx = &valueBottle[V]{ //创建个空壳数据 135 | mutex: &sync.RWMutex{}, 136 | done: false, 137 | res: utils.Zero[V](), // no need to set zero value 138 | err: nil, // no need to set none value 139 | } 140 | a.mp[k] = vx 141 | vx.mutex.Lock() //把这个壳给锁住，再开始计算数据，这时map的锁即可释放，而元素的锁将生效以确保需要同样元素的请求都得等待后面运算结束，即等待元素的释放锁 142 | return vx, vx.mutex 143 | } 144 | 145 | return vx, nil 146 | } 147 | 148 | // Delete removes a key and its associated value from the map. 149 | // Delete 从 map 中删除一个键及其关联的值。 150 | func (a *Map[K, V]) Delete(k K) { 151 | a.mutex.Lock() 152 | defer a.mutex.Unlock() 153 | delete(a.mp, k) 154 | } 155 | 156 | // Len returns the number of key-value pairs in the map. 157 | // Len 返回 map 中键值对的数量。 158 | func (a *Map[K, V]) Len() int { 159 | a.mutex.RLock() 160 | defer a.mutex.RUnlock() 161 | return len(a.mp) 162 | } 163 | 164 | // Range iterates over the map, calling the provided function for each key-value pair until it returns false. 165 | // Range 遍历 map，对每个键值对调用提供的函数，直到函数返回 false。 166 | func (a *Map[K, V]) Range(run func(k K, v V, err error, done bool) bool) { 167 | a.mutex.RLock() 168 | defer a.mutex.RUnlock() 169 | for k, v := range a.mp { 170 | if ok := run(k, v.res, v.err, v.done); !ok { 171 | return 172 | } 173 | } 174 | } 175 | -------------------------------------------------------------------------------- /cachemap/cache_map_test.go: -------------------------------------------------------------------------------- 1 | package cachemap_test 2 | 3 | import ( 4 | "math/rand/v2" 5 | "testing" 6 | 7 | "github.com/pkg/errors" 8 | "github.com/stretchr/testify/require" 9 | "github.com/yyle88/mutexmap/cachemap" 10 | ) 11 | 12 | func TestNew(t *testing.T) { 13 | cache := cachemap.New[string, int]() 14 | require.NotNil(t, cache) 15 | require.Equal(t, 0, cache.Len()) 16 | 17 | // Verify default capacity by adding elements 18 | const constK = "abc" 19 | cache.Set(constK, 42) 20 | res, err, done := cache.Get(constK) 21 | t.Log(res, err) 22 | require.True(t, done) 23 | require.NoError(t, err) 24 | require.Equal(t, 42, res) 25 | } 26 | 27 | func TestNewMap(t *testing.T) { 28 | cache := cachemap.NewMap[string, int](100) 29 | 30 | calc := func() (int, error) { 31 | num := rand.IntN(100) 32 | if num < 50 { 33 | return -1, errors.New("wrong") 34 | } 35 | return num, nil 36 | } 37 | for idx := 0; idx < 10; idx++ { 38 | t.Log("(", idx, ")") 39 | const constK = "abc" 40 | res1, err1 := cache.Getset(constK, calc) 41 | t.Log(res1, err1) 42 | res2, err2 := cache.Getset(constK, calc) 43 | t.Log(res2, err2) 44 | 45 | if err1 != nil || err2 != nil { 46 | require.ErrorIs(t, err1, err2) 47 | } 48 | require.Equal(t, res1, res2) 49 | 50 | res3, err3, done := cache.Get(constK) 51 | require.True(t, done) 52 | if err2 != nil || err3 != nil { 53 | require.ErrorIs(t, err2, err3) 54 | } 55 | require.Equal(t, res2, res3) 56 | 57 | cache.Delete(constK) 58 | 59 | t.Log(cache.Len()) 60 | } 61 | } 62 | 63 | func TestGet(t *testing.T) { 64 | cache := cachemap.NewMap[string, int](100) 65 | 66 | const constK = "abc" 67 | res, err, done := cache.Get(constK) 68 | t.Log(res, err) 69 | require.False(t, done) 70 | require.Error(t, err) 71 | require.Equal(t, "not exist", err.Error()) 72 | require.Equal(t, 0, res) 73 | 74 | cache.Set(constK, 42) 75 | res, err, done = cache.Get(constK) 76 | t.Log(res, err) 77 | require.True(t, done) 78 | require.NoError(t, err) 79 | require.Equal(t, 42, res) 80 | } 81 | 82 | func TestSet(t *testing.T) { 83 | cache := cachemap.NewMap[string, int](100) 84 | 85 | calc := func() (int, error) { 86 | num := rand.IntN(100) 87 | if num < 50 { 88 | return -1, errors.New("wrong") 89 | } 90 | return num, nil 91 | } 92 | for idx := 0; idx < 10; idx++ { 93 | t.Log("(", idx, ")") 94 | const constK = "abc" 95 | var res0 = rand.IntN(100) 96 | cache.Set(constK, res0) 97 | 98 | res1, err1, done := cache.Get(constK) 99 | t.Log(res1, err1) 100 | require.True(t, done) 101 | require.NoError(t, err1) 102 | require.Equal(t, res0, res1) 103 | 104 | res2, err2 := cache.Getset(constK, calc) 105 | t.Log(res2, err2) 106 | require.NoError(t, err2) 107 | require.Equal(t, res0, res2) 108 | 109 | cache.Delete(constK) 110 | t.Log(cache.Len()) 111 | } 112 | } 113 | 114 | func TestSetKv(t *testing.T) { 115 | cache := cachemap.NewMap[string, int](100) 116 | 117 | calc := func() (int, error) { 118 | num := rand.IntN(100) 119 | if num < 50 { 120 | return -1, errors.New("wrong") 121 | } 122 | return num, nil 123 | } 124 | for idx := 0; idx < 10; idx++ { 125 | t.Log("(", idx, ")") 126 | const constK = "abc" 127 | var res0 = rand.IntN(100) 128 | cache.SetKv(constK, res0) 129 | 130 | res1, err1, done := cache.Get(constK) 131 | t.Log(res1, err1) 132 | require.True(t, done) 133 | require.NoError(t, err1) 134 | require.Equal(t, res0, res1) 135 | 136 | res2, err2 := cache.Getset(constK, calc) 137 | t.Log(res2, err2) 138 | require.NoError(t, err2) 139 | require.Equal(t, res0, res2) 140 | 141 | cache.Delete(constK) 142 | t.Log(cache.Len()) 143 | } 144 | } 145 | 146 | func TestSetKe(t *testing.T) { 147 | cache := cachemap.NewMap[string, int](100) 148 | 149 | calc := func() (int, error) { 150 | num := rand.IntN(100) 151 | if num < 50 { 152 | return -1, errors.New("wrong") 153 | } 154 | return num, nil 155 | } 156 | for idx := 0; idx < 10; idx++ { 157 | t.Log("(", idx, ")") 158 | const constK = "abc" 159 | err0 := errors.New("wrong") 160 | cache.SetKe(constK, err0) 161 | 162 | res1, err1, done := cache.Get(constK) 163 | t.Log(res1, err1) 164 | require.True(t, done) 165 | require.ErrorIs(t, err0, err1) 166 | require.Equal(t, 0, res1) // Zero value for int 167 | 168 | res2, err2 := cache.Getset(constK, calc) 169 | t.Log(res2, err2) 170 | require.ErrorIs(t, err0, err2) 171 | require.Equal(t, 0, res2) 172 | 173 | cache.Delete(constK) 174 | t.Log(cache.Len()) 175 | } 176 | } 177 | 178 | func TestSetVe(t *testing.T) { 179 | cache := cachemap.NewMap[string, int](100) 180 | 181 | calc := func() (int, error) { 182 | num := rand.IntN(100) 183 | if num < 50 { 184 | return -1, errors.New("wrong") 185 | } 186 | return num, nil 187 | } 188 | for idx := 0; idx < 10; idx++ { 189 | t.Log("(", idx, ")") 190 | const constK = "abc" 191 | var res0 = rand.IntN(100) 192 | var err0 error 193 | if res0 < 50 { 194 | res0 = -1 195 | err0 = errors.New("wrong") 196 | } 197 | cache.SetVe(constK, res0, err0) 198 | 199 | res1, err1 := cache.Getset(constK, calc) 200 | t.Log(res1, err1) 201 | 202 | if err0 != nil || err1 != nil { 203 | t.Log(err0) 204 | t.Log(err1) 205 | require.ErrorIs(t, err0, err1) 206 | } 207 | require.Equal(t, res0, res1) 208 | 209 | res2, err2 := cache.Getset(constK, calc) 210 | t.Log(res2, err2) 211 | 212 | if err1 != nil || err2 != nil { 213 | require.ErrorIs(t, err1, err2) 214 | } 215 | require.Equal(t, res1, res2) 216 | 217 | res3, err3, done := cache.Get(constK) 218 | require.True(t, done) 219 | if err2 != nil || err3 != nil { 220 | require.ErrorIs(t, err2, err3) 221 | } 222 | require.Equal(t, res2, res3) 223 | 224 | cache.Delete(constK) 225 | 226 | t.Log(cache.Len()) 227 | } 228 | } 229 | 230 | func TestDelete(t *testing.T) { 231 | cache := cachemap.NewMap[string, int](100) 232 | 233 | for idx := 0; idx < 10; idx++ { 234 | t.Log("(", idx, ")") 235 | const constK = "abc" 236 | var res0 = rand.IntN(100) 237 | cache.Set(constK, res0) 238 | 239 | res1, err1, done := cache.Get(constK) 240 | t.Log(res1, err1) 241 | require.True(t, done) 242 | require.NoError(t, err1) 243 | require.Equal(t, res0, res1) 244 | 245 | cache.Delete(constK) 246 | 247 | res2, err2, done2 := cache.Get(constK) 248 | t.Log(res2, err2) 249 | require.False(t, done2) 250 | require.Error(t, err2) 251 | require.Equal(t, "not exist", err2.Error()) 252 | require.Equal(t, 0, res2) 253 | 254 | t.Log(cache.Len()) 255 | } 256 | } 257 | 258 | func TestLen(t *testing.T) { 259 | cache := cachemap.NewMap[string, int](100) 260 | 261 | for idx := 0; idx < 10; idx++ { 262 | t.Log("(", idx, ")") 263 | key := "key" + string(rune('A'+idx)) 264 | var res0 = rand.IntN(100) 265 | cache.Set(key, res0) 266 | 267 | t.Log("Len:", cache.Len()) 268 | require.Equal(t, idx+1, cache.Len()) 269 | 270 | res1, err1, done := cache.Get(key) 271 | t.Log(res1, err1) 272 | require.True(t, done) 273 | require.NoError(t, err1) 274 | require.Equal(t, res0, res1) 275 | } 276 | 277 | for idx := 0; idx < 10; idx++ { 278 | key := "key" + string(rune('A'+idx)) 279 | cache.Delete(key) 280 | t.Log("Len after delete:", cache.Len()) 281 | require.Equal(t, 9-idx, cache.Len()) 282 | } 283 | } 284 | 285 | func TestRange(t *testing.T) { 286 | cache := cachemap.NewMap[string, int](100) 287 | 288 | // Populate map with random values 289 | expected := make(map[string]int) 290 | for idx := 0; idx < 10; idx++ { 291 | key := "key" + string(rune('A'+idx)) 292 | value := rand.IntN(100) 293 | cache.Set(key, value) 294 | expected[key] = value 295 | } 296 | 297 | // Test Range 298 | collected := make(map[string]int) 299 | cache.Range(func(k string, v int, err error, done bool) bool { 300 | t.Log("Range:", k, v, err, done) 301 | require.True(t, done) 302 | require.NoError(t, err) 303 | collected[k] = v 304 | return true 305 | }) 306 | 307 | // Verify collected values 308 | for k, v := range expected { 309 | v2, ok := collected[k] 310 | require.True(t, ok) 311 | require.Equal(t, v, v2) 312 | } 313 | require.Equal(t, len(expected), len(collected)) 314 | 315 | // Test Range with early termination 316 | count := 0 317 | cache.Range(func(k string, v int, err error, done bool) bool { 318 | count++ 319 | return count < 5 // Stop after 5 iterations 320 | }) 321 | require.Equal(t, 5, count) 322 | } 323 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/yyle88/mutexmap 2 | 3 | go 1.22.6 4 | 5 | require ( 6 | github.com/pkg/errors v0.9.1 7 | github.com/stretchr/testify v1.10.0 8 | ) 9 | 10 | require ( 11 | github.com/davecgh/go-spew v1.1.1 // indirect 12 | github.com/pmezard/go-difflib v1.0.0 // indirect 13 | gopkg.in/yaml.v3 v3.0.1 // indirect 14 | ) 15 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= 2 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= 3 | github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= 4 | github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= 5 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= 6 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= 7 | github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= 8 | github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= 9 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= 10 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= 11 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= 12 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= 13 | -------------------------------------------------------------------------------- /internal/utils/zero.go: -------------------------------------------------------------------------------- 1 | package utils 2 | 3 | func Zero[T any]() (x T) { 4 | return x 5 | } 6 | -------------------------------------------------------------------------------- /internal/utils/zero_test.go: -------------------------------------------------------------------------------- 1 | package utils_test 2 | 3 | import ( 4 | "testing" 5 | 6 | "github.com/stretchr/testify/require" 7 | "github.com/yyle88/mutexmap/internal/utils" 8 | ) 9 | 10 | func TestZero(t *testing.T) { 11 | res := utils.Zero[int]() 12 | t.Log(res) 13 | require.Zero(t, res) 14 | 15 | require.Zero(t, utils.Zero[string]()) 16 | require.Zero(t, utils.Zero[float64]()) 17 | require.Zero(t, utils.Zero[uint32]()) 18 | require.Zero(t, utils.Zero[bool]()) 19 | require.Zero(t, utils.Zero[int64]()) 20 | } 21 | -------------------------------------------------------------------------------- /mutex_map.go: -------------------------------------------------------------------------------- 1 | package mutexmap 2 | 3 | import ( 4 | "sync" 5 | 6 | "github.com/yyle88/mutexmap/internal/utils" 7 | ) 8 | 9 | // Map provides a thread-safe map implementation using a sync.RWMutex. 10 | // Map 提供了一个使用 sync.RWMutex 的线程安全 map 实现。 11 | type Map[K comparable, V any] struct { 12 | mp map[K]V // The underlying map. 内部 map。 13 | mutex *sync.RWMutex // Mutex for synchronizing access. 用于同步访问的互斥锁。 14 | } 15 | 16 | // New creates a new thread-safe map. 17 | // New 创建线程安全 map。 18 | func New[K comparable, V any]() *Map[K, V] { 19 | return NewMap[K, V](8) 20 | } 21 | 22 | // NewMap creates a new thread-safe map. 23 | // NewMap 创建线程安全 map。 24 | func NewMap[K comparable, V any](cap int) *Map[K, V] { 25 | return &Map[K, V]{ 26 | mp: make(map[K]V, cap), // Initialize the internal map. 初始化内部 map。 27 | mutex: &sync.RWMutex{}, // Initialize the RWMutex. 初始化读写锁。 28 | } 29 | } 30 | 31 | // Get retrieves the value associated with the given key. It returns the value and a boolean indicating whether the key exists. 32 | // Get 获取与指定键关联的值，它返回值以及一个布尔值，指示键是否存在。 33 | func (a *Map[K, V]) Get(k K) (V, bool) { 34 | a.mutex.RLock() // Acquire read lock. 获取读锁。 35 | defer a.mutex.RUnlock() // Ensure lock is released. 确保锁被释放。 36 | if v, ok := a.mp[k]; ok { 37 | return v, ok 38 | } else { 39 | return utils.Zero[V](), false // Explicitly return zero value if not found. 未找到时显式返回零值。 40 | } 41 | } 42 | 43 | // Set inserts or updates the value for the given key into map. 44 | // Set 插入或更新指定键的值。 45 | func (a *Map[K, V]) Set(k K, v V) { 46 | a.mutex.Lock() // Acquire write lock. 获取写锁。 47 | defer a.mutex.Unlock() // Ensure lock is released. 确保锁被释放。 48 | a.mp[k] = v 49 | } 50 | 51 | // Delete removes the key-value. 52 | // Delete 移除与指定键关联的键值对。 53 | func (a *Map[K, V]) Delete(k K) { 54 | a.mutex.Lock() // Acquire write lock. 获取写锁。 55 | defer a.mutex.Unlock() // Ensure lock is released. 确保锁被释放。 56 | delete(a.mp, k) 57 | } 58 | 59 | // Len returns the number of key-value pairs in the map. 60 | // Len 返回 map 中键值对的数量。 61 | func (a *Map[K, V]) Len() int { 62 | a.mutex.RLock() // Acquire read lock. 获取读锁。 63 | defer a.mutex.RUnlock() // Ensure lock is released. 确保锁被释放。 64 | return len(a.mp) 65 | } 66 | 67 | // Range iterates over all key-value pairs in the map, applying the given function. If the function returns false, the iteration stops. 68 | // Range 遍历 map 中的所有键值对，并应用给定的函数。 如果函数返回 false，迭代将停止。 69 | func (a *Map[K, V]) Range(run func(k K, v V) bool) { 70 | a.mutex.RLock() // Acquire read lock. 获取读锁。 71 | defer a.mutex.RUnlock() // Ensure lock is released. 确保锁被释放。 72 | for k, v := range a.mp { 73 | if ok := run(k, v); !ok { // Stop iteration if the callback returns false. 如果回调返回 false，则停止迭代。 74 | return 75 | } 76 | } 77 | } 78 | 79 | // Getset retrieves the value associated with the key, or computes and stores a new value if the key does not exist. 80 | // It returns the value and a boolean indicating whether a new value was created. 81 | // Getset 获取与键关联的值，如果键不存在，则计算并存储新值。 82 | // 它返回值以及一个布尔值，指示是否创建了新值。 83 | func (a *Map[K, V]) Getset(k K, calculate func() V) (v V, created bool) { 84 | if v, ok := a.Get(k); ok { // Attempt to read the value with a read lock. 尝试用读锁读取值。 85 | return v, false // Return existing value if found. 如果找到，返回已存在的值。 86 | } 87 | // 读锁释放，启动写锁，但假设有两个线程同时读不到，就都会同时占用写锁。 88 | a.mutex.Lock() 89 | defer a.mutex.Unlock() 90 | // 增加读锁以后二次确认内容是否在 map 里面，这样第二次占用写锁的线程就不会创建新对象。 91 | if v, ok := a.mp[k]; ok { // Double-check under write lock. 在写锁下再次检查。 92 | return v, false // Return the existing value if found. 如果找到，返回已有值。 93 | } 94 | // 当内容确实不在 map 里时，即首次占用写锁时，这才创建新对象，设置到 map 里。 95 | v = calculate() // Calculate the value. 计算值。 96 | // This function might be expensive. If this is a concern, consider alternative caching solutions. 97 | // 这个函数可能耗时较长，如果对此介意，可以考虑使用其他缓存方案。 98 | a.mp[k] = v 99 | return v, true // Return the new value and indicate it was created. 返回新值并指示是新创建的。 100 | } 101 | -------------------------------------------------------------------------------- /mutex_map_test.go: -------------------------------------------------------------------------------- 1 | package mutexmap_test 2 | 3 | import ( 4 | "strconv" 5 | "sync" 6 | "testing" 7 | 8 | "github.com/stretchr/testify/require" 9 | "github.com/yyle88/mutexmap" 10 | ) 11 | 12 | func TestMap_Getset(t *testing.T) { 13 | a := mutexmap.NewMap[int, string](0) 14 | { 15 | v, created := a.Getset(0, func() string { 16 | return "abc" 17 | }) 18 | require.True(t, created) 19 | require.Equal(t, v, "abc") 20 | } 21 | { 22 | v, created := a.Getset(0, func() string { 23 | return "xyz" 24 | }) 25 | require.False(t, created) 26 | require.Equal(t, v, "abc") // not change value when already exist. 27 | } 28 | } 29 | 30 | func TestMutexMap_SetAndGet(t *testing.T) { 31 | m := mutexmap.New[int, string]() 32 | m.Set(1, "value1") 33 | 34 | // 测试正常获取 35 | value, ok := m.Get(1) 36 | require.True(t, ok) 37 | require.Equal(t, "value1", value) 38 | 39 | // 测试获取不存在的键 40 | _, ok = m.Get(2) 41 | require.False(t, ok) 42 | } 43 | 44 | func TestMutexMap_ConcurrencyRun(t *testing.T) { 45 | m := mutexmap.New[int, string]() 46 | var wg sync.WaitGroup 47 | 48 | // 模拟并发写入 49 | for i := 0; i < 100; i++ { 50 | wg.Add(1) 51 | go func(i int) { 52 | defer wg.Done() 53 | m.Set(i, "v"+strconv.Itoa(i)) 54 | }(i) 55 | } 56 | 57 | wg.Wait() 58 | 59 | // 验证写入结果 60 | for i := 0; i < 100; i++ { 61 | value, ok := m.Get(i) 62 | require.True(t, ok) 63 | require.Equal(t, "v"+strconv.Itoa(i), value) 64 | } 65 | } 66 | --------------------------------------------------------------------------------