symlock

README

symlock

A symbolic lock implementation for Go.

Introduction

SymLocks (or named locks) provide mutual exclusion on a string value rather than a specific lock object. This can be useful in situations where the complete set of mutex points isn’t immediately known, or may be too large for up front setup to be practical.

Example

Use a SymLock like this:

s := symlock.New()

s.WithMutex("some string value symbolising a mutex point", func() {
    // Do some things which require mutex on something represented by the provided string
})

By default, New() will return a SymLock with twice the number of partitions as there are processors (the degree of concurrency is limited by the number of partitions). You can specify the number of partitions like this:

s := symlock.NewWithPartitions(16)

All code using the same SymLock with the same string will be mutexed from each other:

go s.WithMutex("apple", func() {
    // Do some stuff
})

go s.WithMutex("apple", func() {
    // Do some more stuff, with mutually exclusive locking from the above
})

go s.WithMutex("pear", func() {
    // Do some stuff that can run concurrently with code using "apple" as
    // the mutex symbol, but not with other code that might be using "pear"
})

Documentation

Index

• type SymLock
  • func New() SymLock
  • func NewWithPartitions(n int) SymLock

Types

type SymLock

type SymLock interface {
	WithMutex(symbol string, action func())
}

SymLock is the interface for a symbolic lock.

WithMutex executes the specified action using the given symbol for mutual exclusion. No two goroutines using the same SymLock and the same symbol will execute concurrently with each other.

func New

func New() SymLock

New creates and returns a new SymLock with a default number of partitions, equal to twice the number of processors.

func NewWithPartitions

func NewWithPartitions(n int) SymLock

NewWithPartitions creates and returns a new SymLock with the specified number of partitions. The number of partitions effectively places an upper limit on the degree of concurrency.