shardedmap

README

shardedmap

This project contains a threadsafe sharded map implementation in Go.

Installation

go get github.com/dtomasi/shardedmap

Usage

TBD

Notice

The idea of splitting maps into shards to solve parallel access issues is not new. I borrowed some ideas from here:

https://github.com/orcaman/concurrent-map

https://github.com/allegro/bigcache

LICENCE

see LICENCE

Documentation

Overview

Package shardedmap contains another treadsafe sharded map implementation for go

Index

• Variables
• func HashFnv1a32(key string) uint
• func HashFnv1a64(key string) uint
• type AtomicShard
  • func (s *AtomicShard) All() ShardDataMap
  • func (s *AtomicShard) Clear()
  • func (s *AtomicShard) Count() uint
  • func (s *AtomicShard) Get(key uint) (interface{}, error)
  • func (s *AtomicShard) Has(key uint) bool
  • func (s *AtomicShard) Remove(key uint)
  • func (s *AtomicShard) Set(key uint, value ShardTuple)
• type KeyHashFunc
• type Map
  • func New(opts ...MapOption) *Map
  • func (m *Map) All() map[string]interface{}
  • func (m *Map) Clear()
  • func (m *Map) Count() int
  • func (m *Map) Get(key string) (interface{}, error)
  • func (m *Map) Has(key string) bool
  • func (m *Map) MarshalJSON() ([]byte, error)
  • func (m *Map) MustGet(key string) interface{}
  • func (m *Map) Range() <-chan ShardTuple
  • func (m *Map) RangeWithCallback(cb func(key string, value interface{}) interface{})
  • func (m *Map) Remove(key string)
  • func (m *Map) Set(key string, value interface{})
  • func (m *Map) UnmarshalJSON(b []byte) error
• type MapOption
  • func WithCustomKeyHashFunc(f KeyHashFunc) MapOption
  • func WithCustomShardProvider(provider ShardProviderFunc) MapOption
  • func WithShardCount(count int) MapOption
• type MutexShard
  • func (s *MutexShard) All() ShardDataMap
  • func (s *MutexShard) Clear()
  • func (s *MutexShard) Count() uint
  • func (s *MutexShard) Get(key uint) (interface{}, error)
  • func (s *MutexShard) Has(key uint) bool
  • func (s *MutexShard) Remove(key uint)
  • func (s *MutexShard) Set(key uint, value ShardTuple)
• type Shard
  • func NewAtomicShard() Shard
  • func NewMutexShard() Shard
• type ShardDataMap
• type ShardProviderFunc
• type ShardTuple
• type Tuple
  • func NewTuple(key string, value interface{}) Tuple
  • func (t Tuple) GetKey() string
  • func (t Tuple) GetValue() interface{}

Variables

var (
	DefaultShardCount        uint              = 8             //nolint:gochecknoglobals
	DefaultShardProviderFunc ShardProviderFunc = NewMutexShard //nolint:gochecknoglobals
	DefaultKeyHashFunc       KeyHashFunc       = HashFnv1a64   //nolint:gochecknoglobals
)

DefaultShardCount allows overwriting package default for New().

Functions

func HashFnv1a32

func HashFnv1a32(key string) uint

func HashFnv1a64

func HashFnv1a64(key string) uint

Types

type AtomicShard

type AtomicShard struct {
	// contains filtered or unexported fields
}

AtomicShard represents a shard used in Map.

func (*AtomicShard) All

func (s *AtomicShard) All() ShardDataMap

All see: interfaces.Shard.

func (*AtomicShard) Clear

func (s *AtomicShard) Clear()

Clear see: interfaces.Shard.

func (*AtomicShard) Count

func (s *AtomicShard) Count() uint

Count see: interfaces.Shard.

func (*AtomicShard) Get

func (s *AtomicShard) Get(key uint) (interface{}, error)

Get see: interfaces.Shard.

func (*AtomicShard) Has

func (s *AtomicShard) Has(key uint) bool

Has see: interfaces.Shard.

func (*AtomicShard) Remove

func (s *AtomicShard) Remove(key uint)

Remove see: interfaces.Shard.

func (*AtomicShard) Set

func (s *AtomicShard) Set(key uint, value ShardTuple)

Set see: interfaces.Shard.

type KeyHashFunc

type KeyHashFunc func(key string) uint

KeyHashFunc defines a function that is used create a hash from a given key.

type Map

type Map struct {
	// contains filtered or unexported fields
}

Map represents the sharded map.

func New

func New(opts ...MapOption) *Map

New creates a new sharded map.

func (*Map) All

func (m *Map) All() map[string]interface{}

All returns a flat map of all keys and values across all shards.

func (*Map) Clear

func (m *Map) Clear()

Clear clears all data across all shards.

func (*Map) Count

func (m *Map) Count() int

Count returns the count of all elements across all shards.

func (*Map) Get

func (m *Map) Get(key string) (interface{}, error)

Get returns the value for given key or an error.

func (*Map) Has

func (m *Map) Has(key string) bool

func (*Map) MarshalJSON

func (m *Map) MarshalJSON() ([]byte, error)

MarshalJSON supports custom marshaling by implementing json.Marshaler interface.

func (*Map) MustGet

func (m *Map) MustGet(key string) interface{}

MustGet returns the value for a given key or nil.

func (*Map) Range

func (m *Map) Range() <-chan ShardTuple

Range allows iterating over a buffered data set.

func (*Map) RangeWithCallback

func (m *Map) RangeWithCallback(cb func(key string, value interface{}) interface{})

func (*Map) Remove

func (m *Map) Remove(key string)

func (*Map) Set

func (m *Map) Set(key string, value interface{})

func (*Map) UnmarshalJSON

func (m *Map) UnmarshalJSON(b []byte) error

UnmarshalJSON supports custom unmarshaling by implementing json.Unmarshaler interface.

type MapOption

type MapOption func(m *Map)

MapOption defines an option that can be set in Map constructor.

func WithCustomKeyHashFunc

func WithCustomKeyHashFunc(f KeyHashFunc) MapOption

WithCustomKeyHashFunc specifies the function for calculating the shard index for a given key.

func WithCustomShardProvider

func WithCustomShardProvider(provider ShardProviderFunc) MapOption

WithCustomShardProvider specifies the shard provider function to use.

func WithShardCount

func WithShardCount(count int) MapOption

WithShardCount specifies the number of shards.

type MutexShard

type MutexShard struct {
	// contains filtered or unexported fields
}

MutexShard represents a shard used in Map.

func (*MutexShard) All

func (s *MutexShard) All() ShardDataMap

All see: interfaces.Collection.

func (*MutexShard) Clear

func (s *MutexShard) Clear()

Clear see: interfaces.Collection.

func (*MutexShard) Count

func (s *MutexShard) Count() uint

Count see: interfaces.Collection.

func (*MutexShard) Get

func (s *MutexShard) Get(key uint) (interface{}, error)

Get see: interfaces.Collection.

func (*MutexShard) Has

func (s *MutexShard) Has(key uint) bool

Has see: interfaces.Collection.

func (*MutexShard) Remove

func (s *MutexShard) Remove(key uint)

Remove see: interfaces.Collection.

func (*MutexShard) Set

func (s *MutexShard) Set(key uint, value ShardTuple)

Set see: interfaces.Collection.

type Shard

type Shard interface {

	// All returns all contained data as KVMap.
	All() ShardDataMap

	// Get returns a value from Collection.
	Get(uint) (interface{}, error)

	// Set sets a value to Collection.
	Set(uint, ShardTuple)

	// Has checks the existence of a key/value in Collection.
	Has(uint) bool

	// Remove removes an element by key from Collection.
	Remove(uint)

	// Count returns the count of elements in Collection.
	Count() uint

	// Clear resets all data in Collection.
	Clear()
}

Shard defines the interface that can be passed to map.

func NewAtomicShard

func NewAtomicShard() Shard

NewAtomicShard creates a new AtomicShard.

func NewMutexShard

func NewMutexShard() Shard

NewMutexShard creates a new Shard.

type ShardDataMap

type ShardDataMap map[uint]ShardTuple

type ShardProviderFunc

type ShardProviderFunc func() Shard

ShardProviderFunc defines a function that is used to create Shards while initializing a Map.

type ShardTuple

type ShardTuple interface {
	GetKey() string
	GetValue() interface{}
}

type Tuple

type Tuple struct {
	// contains filtered or unexported fields
}

func NewTuple

func NewTuple(key string, value interface{}) Tuple

func (Tuple) GetKey

func (t Tuple) GetKey() string

func (Tuple) GetValue

func (t Tuple) GetValue() interface{}