csmap

README

Concurrent Swiss Map

Concurrent Swiss Map is an open-source Go library that provides a high-performance, thread-safe generic concurrent hash map implementation designed to handle concurrent access efficiently. It's built with a focus on simplicity, speed, and reliability, making it a solid choice for scenarios where concurrent access to a hash map is crucial.

Uses dolthub/swiss map implementation under the hood.

Installation

Supports 1.19+ Go versions because of Go Generics

go get github.com/gnazaryan/concurrent-swiss-map

Usage

New functions will be added soon...

package main

import (
	"hash/fnv"

	csmap "github.com/gnazaryan/concurrent-swiss-map"
)

func main() {
	myMap := csmap.Create[string, int](
		// set the number of map shards. the default value is 32.
		csmap.WithShardCount[string, int](32),

		// if don't set custom hasher, use the built-in maphash.
		csmap.WithCustomHasher[string, int](func(key string) uint64 {
			hash := fnv.New64a()
			hash.Write([]byte(key))
			return hash.Sum64()
		}),

		// set the total capacity, every shard map has total capacity/shard count capacity. the default value is 0.
		csmap.WithSize[string, int](1000),
	)

	key := "swiss-map"
	myMap.Store(key, 10)

	val, ok := myMap.Load(key)
	println("load val:", val, "exists:", ok)

	deleted := myMap.Delete(key)
	println("deleted:", deleted)

	ok = myMap.Has(key)
	println("has:", ok)

	empty := myMap.IsEmpty()
	println("empty:", empty)

	myMap.SetIfAbsent(key, 11)

	myMap.Range(func(key string, value int) (stop bool) {
		println("range:", key, value)
		return true
	})

	count := myMap.Count()
	println("count:", count)

	// Output:
	// load val: 10 exists: true
	// deleted: true
	// has: false
	// empty: true
	// range: swiss-map 11
	// count: 1
}

Basic Architecture

Benchmark Test

Benchmark was made on:

• Apple M1 Max
• 32 GB memory

Benchmark test results can be obtained by running this file on local computers.

Benchmark Results

• Memory usage of the concurrent swiss map is better than other map implementations in all checked test scenarios.
• In high concurrent systems, the concurrent swiss map is faster, but in systems containing few concurrent operations, it works similarly to RWMutexMap.

Documentation

Index

• func WithCustomHasher[K comparable, V any](h func(key K) uint64) func(csMap *CsMap[K, V])
• func WithShardCount[K comparable, V any](count uint64) func(csMap *CsMap[K, V])
• func WithSize[K comparable, V any](size uint64) func(csMap *CsMap[K, V])
• type CsMap
  • func Create[K comparable, V any](options ...func(options *CsMap[K, V])) *CsMap[K, V]
  • func (m *CsMap[K, V]) Clear()
  • func (m *CsMap[K, V]) Count() int
  • func (m *CsMap[K, V]) Delete(key K) bool
  • func (m *CsMap[K, V]) DeleteIf(key K, condition func(value V) bool) bool
  • func (m *CsMap[K, V]) DeleteRetrieve(key K) V
  • func (m *CsMap[K, V]) Has(key K) bool
  • func (m *CsMap[K, V]) IsEmpty() bool
  • func (m *CsMap[K, V]) Load(key K) (V, bool)
  • func (m *CsMap[K, V]) LoadLocked(key K, loader func(value V)) bool
  • func (m *CsMap[K, V]) MarshalJSON() ([]byte, error)
  • func (m *CsMap[K, V]) Range(f func(key K, value V) (stop bool))
  • func (m *CsMap[K, V]) RangeDelete(f func(key K, value V) (stop bool))
  • func (m *CsMap[K, V]) SetIf(key K, ...)
  • func (m *CsMap[K, V]) SetIfAbsent(key K, value V)
  • func (m *CsMap[K, V]) SetIfPresent(key K, value V)
  • func (m *CsMap[K, V]) Store(key K, value V)
  • func (m *CsMap[K, V]) StoreCompute(key K, compute func(value V) V) V
  • func (m *CsMap[K, V]) StoreComputeSinglton(key K, compute func(value V) V) V
  • func (m *CsMap[K, V]) UnmarshalJSON(b []byte) error
• type HashShardPair
• type Tuple

Functions

func WithCustomHasher

func WithCustomHasher[K comparable, V any](h func(key K) uint64) func(csMap *CsMap[K, V])

func WithShardCount

func WithShardCount[K comparable, V any](count uint64) func(csMap *CsMap[K, V])

func WithSize

func WithSize[K comparable, V any](size uint64) func(csMap *CsMap[K, V])

Types

type CsMap

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

func Create

func Create[K comparable, V any](options ...func(options *CsMap[K, V])) *CsMap[K, V]

func (*CsMap[K, V]) Clear

func (m *CsMap[K, V]) Clear()

func (*CsMap[K, V]) Count

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

func (*CsMap[K, V]) Delete

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

func (*CsMap[K, V]) DeleteIf

func (m *CsMap[K, V]) DeleteIf(key K, condition func(value V) bool) bool

func (*CsMap[K, V]) DeleteRetrieve

func (m *CsMap[K, V]) DeleteRetrieve(key K) V

func (*CsMap[K, V]) Has

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

func (*CsMap[K, V]) IsEmpty

func (m *CsMap[K, V]) IsEmpty() bool

func (*CsMap[K, V]) Load

func (m *CsMap[K, V]) Load(key K) (V, bool)

func (*CsMap[K, V]) LoadLocked

func (m *CsMap[K, V]) LoadLocked(key K, loader func(value V)) bool

func (*CsMap[K, V]) MarshalJSON

func (m *CsMap[K, V]) MarshalJSON() ([]byte, error)

func (*CsMap[K, V]) Range

func (m *CsMap[K, V]) Range(f func(key K, value V) (stop bool))

Range If the callback function returns true iteration will stop.

func (*CsMap[K, V]) RangeDelete

func (m *CsMap[K, V]) RangeDelete(f func(key K, value V) (stop bool))

Range If the callback function returns true iteration will stop.

func (*CsMap[K, V]) SetIf

func (m *CsMap[K, V]) SetIf(key K, conditionFn func(previousVale V, previousFound bool) (value V, set bool))

func (*CsMap[K, V]) SetIfAbsent

func (m *CsMap[K, V]) SetIfAbsent(key K, value V)

func (*CsMap[K, V]) SetIfPresent

func (m *CsMap[K, V]) SetIfPresent(key K, value V)

func (*CsMap[K, V]) Store

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

func (*CsMap[K, V]) StoreCompute

func (m *CsMap[K, V]) StoreCompute(key K, compute func(value V) V) V

func (*CsMap[K, V]) StoreComputeSinglton

func (m *CsMap[K, V]) StoreComputeSinglton(key K, compute func(value V) V) V

func (*CsMap[K, V]) UnmarshalJSON

func (m *CsMap[K, V]) UnmarshalJSON(b []byte) error

type HashShardPair

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

type Tuple

type Tuple[K comparable, V any] struct {
	Key K
	Val V
}