A Golang lock-free thread-safe HashMap optimized for fastest read access.
It is not a general-use HashMap and currently has slow write performance for write heavy uses.
Example uint8 key map uses:
m := New[uint8, int]()
m.Set(1, 123)
value, ok := m.Get(1)
Example string key map uses:
m := New[string, int]()
m.Set("amount", 123)
value, ok := m.Get("amount")
Using the map to count URL requests:
m := New[string, *int64]()
var i int64
counter, _ := m.GetOrInsert("api/123", &i)
atomic.AddInt64(counter, 1) // increase counter
...
count := atomic.LoadInt64(counter) // read counter
Reading from the hash map for numeric key types in a thread-safe way is faster than reading from a standard Golang map
in an unsafe way and three times faster than Golang's sync.Map:
ReadXsyncMapUint-8 924.5n ± ∞ ¹
ReadHashMapUint-8 1.072µ ± ∞ ¹
ReadHaxMapUint-8 1.296µ ± ∞ ¹
ReadGoMapUintUnsafe-8 1.318µ ± ∞ ¹
ReadGoSyncMapUint-8 3.389µ ± ∞ ¹
ReadSkipMapUint-8 4.820µ ± ∞ ¹
ReadGoMapUintMutex-8 32.62µ ± ∞ ¹
Reading from the map while writes are happening:
ReadHashMapWithWritesUint-8 1.235µ ± ∞ ¹
ReadHaxMapWithWritesUint-8 1.433µ ± ∞ ¹
ReadGoSyncMapWithWritesUint-8 4.503µ ± ∞ ¹
Write performance without any concurrent reads:
WriteGoMapMutexUint-8 21.72µ ± ∞ ¹
WriteHashMapUint-8 27.99µ ± ∞ ¹
WriteGoSyncMapUint-8 78.43µ ± ∞ ¹
The benchmarks were run with Golang 1.24.4 on Linux and a Ryzen 9 5900X CPU using make benchmark-perflock.
-
Technical design decisions have been made based on benchmarks that are stored in an external repository: go-benchmark
-
The library uses a sorted linked list and a slice as an index into that list.
-
The Get() function contains helper functions that have been inlined manually until the Golang compiler will inline them automatically.
-
It optimizes the slice access by circumventing the Golang size check when reading from the slice. Once a slice is allocated, the size of it does not change. The library limits the index into the slice, therefore the Golang size check is obsolete. When the slice reaches a defined fill rate, a bigger slice is allocated and all keys are recalculated and transferred into the new slice.
-
For hashing, specialized xxhash implementations are used that match the size of the key type where available