namespacedMutex

README

golang-namespacedMutex

This Go package enables a theoretically infinite number of mutexes to be stored and accessed based on namespaces.

Example

package main

import (
	"fmt"
	"strconv"
	"sync"

	namespacedMutex "github.com/theTardigrade/golang-namespacedMutex"
)

var mutexManager = namespacedMutex.New(namespacedMutex.Options{
	MutexesBucketCount:            1 << 5,
	MutexesBucketCountMustBePrime: true,
})

func main() {
	numbers := make([]string, 0, 100)
	var wg sync.WaitGroup

	wg.Add(cap(numbers))

	for i := 1; i <= cap(numbers); i++ {
		go func(i int) {
			defer wg.Done()

			// when the Use function is called, a mutex stored
			// under the namespace will automatically be locked
			// before the handler function runs, and unlocked
			// once it's finished
			mutexManager.Use(func() {
				numbers = append(numbers, strconv.Itoa(i))
			}, false, "this-is-the-namespace")
		}(i)
	}

	wg.Wait()
	wg.Add(len(numbers))

	var numbersList string

	for i := 0; i < len(numbers); i++ {
		go func(i int) {
			defer wg.Done()

			// you can also use a mutex directly by calling
			// the GetLocked function
			mutex := mutexManager.GetLocked(false, "another-namespace")
			defer mutex.Unlock()

			numbersList += "(" + numbers[i] + ")"
		}(i)
	}

	wg.Wait()

	fmt.Println(numbersList)
	fmt.Println(len(numbers))
}

Support

If you use this package, or find any value in it, please consider donating:

Documentation

Index

• type Datum
  • func New(opts Options) *Datum
  • func NewDefault() *Datum
  • func (d *Datum) GetLocked(isReadOnly bool, namespaces ...string) (mutex *MutexWrapper)
  • func (d *Datum) GetLockedIfUnique(isReadOnly bool, namespaces []string, excludedNamespaces [][]string) (mutex *MutexWrapper, found bool)
  • func (d *Datum) Use(handler func(), isReadOnly bool, namespaces ...string)
• type MutexWrapper
  • func (m *MutexWrapper) Raw() *sync.RWMutex
  • func (m *MutexWrapper) Unlock()
• type Options

Types

type Datum

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

Datum is used as the main return type, producing namespaced mutexes on demand.

func New

func New(opts Options) *Datum

New creates a new Datum based on the given options; default options will be used, if necessary.

func NewDefault

func NewDefault() *Datum

NewDefault is equivalent to the New constructor function with default options.

func (*Datum) GetLocked

func (d *Datum) GetLocked(
	isReadOnly bool,
	namespaces ...string,
) (mutex *MutexWrapper)

GetLocked returns a locked mutex based on the given namespaces. The mutex must be unlocked after use, and its lock will be either read-only or read-write.

func (*Datum) GetLockedIfUnique

func (d *Datum) GetLockedIfUnique(
	isReadOnly bool,
	namespaces []string,
	excludedNamespaces [][]string,
) (mutex *MutexWrapper, found bool)

GetLockedIfUnique attempts to return a locked mutex based on the given namespaces. However, if any collection of namespaces from the list of excluded namespaces produces the same mutex, then no mutex will be returned or locked. If a mutex is found, it must be unlocked after use, and its lock will be either read-only or read-write.

func (*Datum) Use

func (d *Datum) Use(handler func(), isReadOnly bool, namespaces ...string)

Use allows code to be run within the handler function while the mutex is automatically locked and unlocked before and after use. It abstracts away the problem of mutual exclusion.

type MutexWrapper

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

MutexWrapper is returned from the GetLocked function; it is a wrapper around a read-write mutex.

func (*MutexWrapper) Raw

func (m *MutexWrapper) Raw() *sync.RWMutex

Raw returns the underlying RWMutex pointer. There should ordinarily be no need to call this function.

func (*MutexWrapper) Unlock

func (m *MutexWrapper) Unlock()

Unlock must be called when the mutex is no longer in use. It can be called multiple times without triggering a panic, but it should ideally only be called once after every use.

type Options

type Options struct {
	MutexesBucketCount            int
	MutexesBucketCountMustBePrime bool
	NamespaceSeparator            string
}

Options is used in the New constructor function.