cmap

Concurrent thread-safe string to string hash table implemented using sharding technique.

cmap is a small Go library that partitions string keys across 32 independently locked shards. It provides concurrent reads and writes without taking one lock for the entire table.

Install

go get github.com/MehdiEidi/cmap

Quick start

package main

import (
	"fmt"

	"github.com/MehdiEidi/cmap/cmap"
)

func main() {
	cache := cmap.New()
	cache.Put("language", "Go")

	if value, ok := cache.Get("language"); ok {
		fmt.Println(value)
	}
}

Create tables with New or From before using them. Get returns a boolean so a stored empty string can be distinguished from a missing key.

System overview

Each operation hashes its key, selects one of 32 shards, and accesses that shard's map while holding its read or write lock.

See the architecture notes for the data path and synchronization model.

API

Function	Behavior
New()	Create an empty table.
From(map[string]string)	Create a table initialized from a map.
Get(key)	Return a value and whether the key exists.
Put(key, value)	Insert or replace a value.
PutIfNotExist(key, value)	Insert only if the key is absent; return whether insertion occurred.
Del(key)	Delete a key and return its prior value and whether it existed.
Has(key)	Report whether a key exists.
Len()	Count entries across the shards.

Read the API reference for details and concurrency notes.

Documentation

• Documentation index
• Architecture and concurrency
• API reference
• Development notes

Compatibility

The module declares Go 1.17. The implementation uses only the Go standard library.