lockstore

Documentation

Index

• type LockStore
  • func New(options LockStoreOptions) LockStore
• type LockStoreOptions
• type LockingGranularity
• type LockingMap
  • func NewLockingMap(options LockingMapOptions) LockingMap
• type LockingMapAddFunc
• type LockingMapCheckFunc
• type LockingMapOptions

Types

type LockStore

type LockStore interface {
	// Lock locks the mutex that is used for the given key
	Lock(key string)

	// TryLock attempts to acquire the lock given the timeout. Returns
	// true if it successfully acquire the lock. False otherwise
	TryLock(key string, timeout time.Duration) (success bool)

	// Unlock unlocks the mutex that is used for the given key
	Unlock(key string)

	// RLock locks the mutex for read-only that is used for the given key
	RLock(key string)

	// TryRLock attempts to acquire the reader lock given the timeout. Returns
	// true if it successfully acquire the lock. False otherwise
	TryRLock(key string, timeout time.Duration) (success bool)

	// RUnlock unlocks the mutex for read-only that is used for the given key
	RUnlock(key string)
}

LockStore provides a way to synchronize using locks based on keys This is mainly use to provide different levels of granularity to avoid lock contention

func New

func New(options LockStoreOptions) LockStore

New creates a new LockStore given the options

type LockStoreOptions

type LockStoreOptions struct {
	// Granularity of the lockstore
	Granularity LockingGranularity

	// LockCount is only relevant if Granularity is ShardedGranularity
	LockCount int
	// contains filtered or unexported fields
}

LockStoreOptions provides options for creating the LockStore

type LockingGranularity

type LockingGranularity int

Specifies locking granularity... Is it one per key, per few keys, per the whole store 0 = whole store 1 = per key 2 = sharded (a pre-defined number of locks)

const (
	StoreGranularity   LockingGranularity = iota
	PerKeyGranularity  LockingGranularity = 1
	ShardedGranularity LockingGranularity = 2
)

type LockingMap

type LockingMap interface {
	// Get returns the value for a key and whether or not it exists. If a
	// ValueCheckFunc was defined in the LockingMapOptions when the map was
	// created then it will be invoked and the value will only be returned if
	// the checker returns true.
	Get(string) (interface{}, bool)

	// Add the value to the map if and only if one of: it doesn't exist or (it exists,
	// a ValueCheckFunc is defined, the check func returns false). Returns a bool
	// where true indicates this value was added to the map, false means it was
	// already in the map (and the ValueCheckFunc if defined returned true).
	Add(string, interface{}) bool

	// AddOrGet for atomically and serially adding a value to the map if it
	// does not exist. If the key is already in the map, the existing value is
	// returned and LockingMapAddFunc is never invoked.
	//
	// If the key does not exist (or a ValueCheckFunc is defined and returns false),
	// the LockingMapAddFunc is called. We guarantee that it will only ever be invoked
	// once at a time. I.e., it is never invoked concurrently.
	AddOrGet(string, LockingMapAddFunc) (interface{}, error)

	// Set will add the value to the map if it does not exist and will overwrite
	// the value in the map if it does exist.
	Set(string, interface{})

	// Delete removes the key from the map if it exists.
	Delete(string)
}

LockingMap is an easy to use wrapper around a map/lockstore that lets you easily handle using a map in a concurrent way. All methods are thread safe, although as you might expect highly concurrent write workloads will lead to serialization. It is not designed for efficiency and is probably not suitable for extremely hot path code (although your mileage may vary). However, this is a suitable class for using long-running LockingMapAddFunc functions that must not be run concurrently.

func NewLockingMap

func NewLockingMap(options LockingMapOptions) LockingMap

NewLockingMap returns a new instance of LockingMap

type LockingMapAddFunc

type LockingMapAddFunc func(string) (interface{}, error)

LockingMapAddFunc is defined by the user and takes as input the key that is is being added and returns a value and possible error.

type LockingMapCheckFunc

type LockingMapCheckFunc func(string, interface{}) bool

LockingMapCheckFunc is given a key and value interface{} and is expected to return a boolean about whether or not the given value is still valid. This can be used to institute TTLs on keys or other style health checks. Note that this function is invoked with locks held so it should be a quick check.

type LockingMapOptions

type LockingMapOptions struct {
	// LockStoreOptions are used to define the granularity of the key locking
	// store.
	LockStoreOptions LockStoreOptions

	// ValueCheckFunc is invoked before the map ever returns a value. See
	// LockingMapCheckFunc for more informatino.
	ValueCheckFunc LockingMapCheckFunc
}

LockingMapOptions for setting options on the map.