prioritylock

README

Priority Lock

Simple lock with priority-based acquisition mechanism.

Requirements

• At least Go 1.21
  • package cmp is required and has been introduced in this version
  • package slices is required and has been introduced in this version

Usage

package main

import (
  "sync"

  prioritylock "github.com/SevenOfSpades/go-prioritylock"
)

func main() {
  l := prioritylock.NewPriorityLockWithDefaultPriorities()
  wg := sync.WaitGroup{}

  wg.Add(1)
  go func() {
    l.Lock(prioritylock.PriorityNeutral)
    defer func() {
      l.Unlock()
      wg.Done()
    }()

    // do stuff
  }()

  go func() {
    l.Lock(prioritylock.PriorityNeutral)
    defer func() {
      l.Unlock()
      wg.Done()
    }()

    // do other stuff
  }()

  wg.Add(1)
  go func() {
    l.Lock(prioritylock.PriorityHigh)
    defer func() {
      l.Unlock()
      wg.Done()
    }()

    // do more important stuff
  }()

  wg.Add(1)
  go func() {
    l.Lock(prioritylock.PriorityAbsolute)
    defer func() {
      l.Unlock()
      wg.Done()
    }()

    // read stuff
  }()

  wg.Wait()
}

In this example goroutine with comment read stuff will have the highest priority in acquiring lock. Second in line is do more important stuff and the least important (in the example) are do stuff and do other stuff, but do stuff is the first lock acquisitor, so it will obtain lock before do other stuff.

Please keep in mind that higher priority does not mean goroutine can "steal" lock from others, it will simply be " next in line" before others in terms of obtaining common lock.

Documentation

Index

• type Priority
  • func DefaultPriorities() []Priority
• type PriorityLock
  • func NewPriorityLock(priorityPool []Priority) *PriorityLock
  • func NewPriorityLockWithDefaultPriorities() *PriorityLock
  • func (l *PriorityLock) Lock(priority Priority)
  • func (l *PriorityLock) Unlock()

Types

type Priority

type Priority int16

const (
	PriorityAbsolute      Priority = math.MaxInt16
	PriorityHigh          Priority = math.MaxInt16 / 2
	PriorityNeutral       Priority = 0
	PriorityLow           Priority = math.MinInt16 / 2
	PriorityInsignificant Priority = math.MinInt16
)

func DefaultPriorities

func DefaultPriorities() []Priority

type PriorityLock

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

PriorityLock holds information about state of current lock. All goroutines operating on common resource should also use common PriorityLock instance.

func NewPriorityLock

func NewPriorityLock(priorityPool []Priority) *PriorityLock

NewPriorityLock creates fresh instance with no active locks.

func NewPriorityLockWithDefaultPriorities

func NewPriorityLockWithDefaultPriorities() *PriorityLock

NewPriorityLockWithDefaultPriorities creates fresh instance with no active locks using DefaultPriorities functions as source of definition for priorities.

func (*PriorityLock) Lock

func (l *PriorityLock) Lock(priority Priority)

Lock will try to acquire lock for current goroutine (or other resource owner). Priority acts as importance level for given goroutine process. If Priority is highest from all acquired locks it means current goroutine will be next to obtain the lock regardless of the order of Lock method invocation. For duplicated Priority values the order of Lock method invocation will determinate next lock owner.

func (*PriorityLock) Unlock

func (l *PriorityLock) Unlock()

Unlock will release lock held by goroutine (or other resource owner). It will remove the highest Priority value from PriorityLock pool and using sync.Cond it will signal all locks to check which goroutine can go next.