syncmap

README

SyncMap - A Type-Safe Interface to sync.Map

SyncMap is a type-safe and generic interface around Go's sync.Map. It simplifies the use of sync.Map through allowing you to define the types on both keys and values.

It makes using sync.Map more simple and more safe through letting you define the types on keys and values when you create the sync.Map.

README

中文说明

Advantages of SyncMap

Using SyncMap has these advantages:

• Generic Type: Helps avoid type mismatches during runtime.
• Clean Code: No need on type assertions from interface{}.
• Simple Usage: Works just same as sync.Map, same methods.

Installation

go get github.com/yyle88/syncmap

How to Use SyncMap

Here's a simple example showing how you can use SyncMap to store and retrieve structured data in a safe way.

Example 1: Storing and Retrieving Data

package main

import (
	"fmt"
	"github.com/yyle88/syncmap"
)

type Student struct {
	Name string
	Age  int
}

func main() {
	// Create a SyncMap with string keys and Student values
	studentMap := syncmap.NewMap[string, *Student]()

	// Add a student to the map
	studentMap.Store("s1", &Student{Name: "Alice", Age: 20})

	// Retrieve the student
	if student, ok := studentMap.Load("s1"); ok {
		fmt.Printf("Student: Name: %s, Age: %d\n", student.Name, student.Age) // Output: Student: Name: Alice, Age: 20
	}
}

⬆️ Source: Source

Explanation

1. Defines Type-Safe Keys and Values: The key is a string, and the value is a Student struct pointer, avoiding the use of interface{} on values.
2. Simplifies Data Access: No need on type assertions like student = v.(*Student) when retrieving data.
3. Works Same with sync.Map: Functions like Store and Load are the same as in sync.Map, so you don't need to learn new methods.

Example 2: Storing, Deleting, and Iterating Through Data

package main

import (
	"fmt"
	"github.com/yyle88/syncmap"
)

type Person struct {
	Name     string
	Age      int
	HomePage string
}

func main() {
	// Create a SyncMap with int keys and *Person values
	mp := syncmap.NewMap[int, *Person]()

	// Add some persons to the map
	mp.Store(1, &Person{
		Name:     "Kratos",
		HomePage: "https://go-kratos.dev/",
	})
	mp.Store(2, &Person{
		Name: "YangYiLe",
		Age:  18,
	})
	mp.Store(3, &Person{
		Name: "DiLiReBa",
		Age:  18,
	})

	// Delete the entry with key 3
	mp.Delete(3)

	// Iterate over all items in the map
	mp.Range(func(key int, value *Person) bool {
		fmt.Println(key, value.Name, value.Age, value.HomePage)
		return true
	})
}

⬆️ Source: Source

Explanation

1. Store and Delete: This example shows how to add multiple items and delete one using the Delete method.
2. Iterate Through Data: The Range method is used to iterate through the key-value pairs in the map, which simplifies traversing the map.
3. Simplified Operations: Just like with the previous example, no type assertions are needed, and the usage is straightforward.

---

SyncMap API

SyncMap provides the following functions:

Function	Description
Store(key, value)	Adds or updates a key-value.
Load(key)	Retrieves the value.
LoadOrStore(key, value)	Returns the value if it exists; otherwise, adds a new item.
Delete(key)	Removes the item from the map.
Range(func)	Iterates through each item in the map.
Has(key)	Checks if a key exists in the map.
Count()	Returns the count of items in the map.
Keys()	Returns the keys from the map.
Values()	Returns the values from the map.

Same as sync.Map with extra functions.

---

Examples

Atomic Operations

LoadOrStore - Get existing or store new value:

value, loaded := m.LoadOrStore("key", "default")
if loaded {
    // Value existed, returned existing value
} else {
    // Value was stored, returned new value
}

Swap - Replace value and get previous:

previous, existed := m.Swap("key", "new-value")
if existed {
    fmt.Println("Previous value:", previous)
}

Comparison Operations

CompareAndSwap - Update when value matches:

success := m.CompareAndSwap("key", "old-value", "new-value")
if success {
    // Value was updated
}

CompareAndDelete - Delete when value matches:

deleted := m.CompareAndDelete("key", "expected-value")
if deleted {
    // Item was deleted
}

Helper Functions

Check existence:

if m.Has("key") {
    // Key exists in map
}

Get count of items:

count := m.Count()
fmt.Println("Map has", count, "items")

Get the keys:

keys := m.Keys()
for _, k := range keys {
    fmt.Println("Key:", k)
}

Get the values:

values := m.Values()
for _, v := range values {
    fmt.Println("Value:", v)
}

---

📄 License

MIT License. See LICENSE.

---

🤝 Contributing

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Found a mistake? Open an issue on GitHub with reproduction steps
• 💡 Have a feature idea? Create an issue to discuss the suggestion
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes and use significant commit messages
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars

Documentation

Index

• type Map
  • func New[K comparable, V any]() *Map[K, V]
  • func NewMap[K comparable, V any]() *Map[K, V]
  • func (m *Map[K, V]) CompareAndDelete(key K, value V) bool
  • func (m *Map[K, V]) CompareAndSwap(key K, old, new V) bool
  • func (m *Map[K, V]) Count() (size int)
  • func (m *Map[K, V]) Debug()
  • func (m *Map[K, V]) Delete(key K)
  • func (m *Map[K, V]) GetMap() map[K]V
  • func (m *Map[K, V]) Has(key K) bool
  • func (m *Map[K, V]) Keys() (keys []K)
  • func (m *Map[K, V]) Load(key K) (res V, ok bool)
  • func (m *Map[K, V]) LoadAndDelete(key K) (res V, ok bool)
  • func (m *Map[K, V]) LoadOrStore(key K, new V) (V, bool)
  • func (m *Map[K, V]) Range(run func(key K, value V) bool)
  • func (m *Map[K, V]) SetMap(mp map[K]V)
  • func (m *Map[K, V]) SetSyncMap(mp *Map[K, V])
  • func (m *Map[K, V]) SetSyncMaps(mps ...*Map[K, V])
  • func (m *Map[K, V]) Store(key K, value V)
  • func (m *Map[K, V]) Swap(key K, value V) (pre V, ok bool)
  • func (m *Map[K, V]) Values() (values []V)

Types

type Map

type Map[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Map is a generic type-safe interface to sync.Map. Map 是 sync.Map 的泛型类型安全接口。

func New

func New[K comparable, V any]() *Map[K, V]

New creates a new instance of Map. New 创建一个新的 Map 实例。

func NewMap

func NewMap[K comparable, V any]() *Map[K, V]

NewMap creates a new instance of Map. NewMap 创建一个新的 Map 实例。

func (*Map[K, V]) CompareAndDelete

func (m *Map[K, V]) CompareAndDelete(key K, value V) bool

CompareAndDelete compares the existing value with the given value and deletes the item when both match. CompareAndDelete 比较已存在的值与给定的值，当两者匹配时删除该项。

func (*Map[K, V]) CompareAndSwap

func (m *Map[K, V]) CompareAndSwap(key K, old, new V) bool

CompareAndSwap compares the existing value with the old value and swaps to the new value when both match. CompareAndSwap 将已存在的值与旧值比较，当两者匹配时替换成新值。

func (*Map[K, V]) Count

func (m *Map[K, V]) Count() (size int)

Count returns the count of items in the Map. Count 返回 Map 中的项数量。

func (*Map[K, V]) Debug

func (m *Map[K, V]) Debug()

Debug prints each item to help with debugging. Debug 打印每一项，用于调试。

func (*Map[K, V]) Delete

func (m *Map[K, V]) Delete(key K)

Delete removes the value associated with the given item. Delete 删除与给定项关联的值。

func (*Map[K, V]) GetMap

func (m *Map[K, V]) GetMap() map[K]V

GetMap returns each item as a standard Go map. GetMap 将每一项作为标准 Go map 返回。

func (*Map[K, V]) Has

func (m *Map[K, V]) Has(key K) bool

Has checks if an item exists in the Map. Has 检查项是否存在于 Map 中。

func (*Map[K, V]) Keys

func (m *Map[K, V]) Keys() (keys []K)

Keys gets each item's name from the Map. Keys 获取 Map 中每项的名称。

func (*Map[K, V]) Load

func (m *Map[K, V]) Load(key K) (res V, ok bool)

Load retrieves the value associated with the given item. Load 获取与给定项关联的值。

func (*Map[K, V]) LoadAndDelete

func (m *Map[K, V]) LoadAndDelete(key K) (res V, ok bool)

LoadAndDelete retrieves and removes the value associated with the given item. LoadAndDelete 获取并删除与给定项关联的值。

func (*Map[K, V]) LoadOrStore

func (m *Map[K, V]) LoadOrStore(key K, new V) (V, bool)

LoadOrStore retrieves the value associated with the item, and when the item does not exist, stores and returns the new value. LoadOrStore 获取与项关联的值，当该项不存在时，存储并返回新值。

func (*Map[K, V]) Range

func (m *Map[K, V]) Range(run func(key K, value V) bool)

Range iterates through each item in the map. Range 遍历 map 中的每一项。

func (*Map[K, V]) SetMap

func (m *Map[K, V]) SetMap(mp map[K]V)

SetMap adds and updates items from a standard Go map. SetMap 从标准 Go map 添加和更新项到 Map。

func (*Map[K, V]) SetSyncMap

func (m *Map[K, V]) SetSyncMap(mp *Map[K, V])

SetSyncMap copies each item from a Map. SetSyncMap 从一个 Map 复制每一项到当前 Map。

func (*Map[K, V]) SetSyncMaps

func (m *Map[K, V]) SetSyncMaps(mps ...*Map[K, V])

SetSyncMaps copies each item from multiple Maps. SetSyncMaps 从多个 Map 复制每一项到当前 Map。

func (*Map[K, V]) Store

func (m *Map[K, V]) Store(key K, value V)

Store sets the value of the given item. Store 设置给定项的值。

func (*Map[K, V]) Swap

func (m *Map[K, V]) Swap(key K, value V) (pre V, ok bool)

Swap replaces the value of the given item and returns the old value when it exists. Swap 替换给定项的值，并在存在时返回旧值。

func (*Map[K, V]) Values

func (m *Map[K, V]) Values() (values []V)

Values gets each item's content from the Map. Values 获取 Map 中每项的内容。