README
¶
advsync
advsync provides small, keyed synchronization primitives for Go. It offers
mutexes, read/write mutexes, and semaphores backed by either a regular map or
xsync.Map.
Installation
go get github.com/vitalick/advsync
Usage
package main
import "github.com/vitalick/advsync"
func main() {
semaphore := advsync.NewSemaphore(2)
semaphore.Acquire()
defer func() { _ = semaphore.Release() }()
// Work with at most two concurrent callers.
}
Primitives
NamedMutexandNamedMutexSMmanage an independent mutex for every key.NamedRWMutexandNamedRWMutexSMprovide a keyed read/write mutex.Semaphoreusessync.Cond;SemaphoreChanuses a buffered channel.NamedSemaphore,NamedSemaphoreSM,NamedSemaphoreChan, andNamedSemaphoreChanSMprovide keyed semaphore variants.
Use the same key to acquire and release a named primitive. As with Go's standard synchronization types, a lock must be released by code that holds it.
Benchmarks
Run the benchmark suite with:
go test -run '^$' -bench . -benchmem
The following uncontended results were measured on Windows 11, AMD Ryzen 9
9950X3D, Go 1.26.5, windows/amd64.
| Benchmark | ns/op | B/op | allocs/op |
|---|---|---|---|
NamedMutex |
28.69 | 0 | 0 |
NamedMutexSM |
31.59 | 16 | 2 |
NamedRWMutex |
36.91 | 0 | 0 |
NamedRWMutexSM |
42.27 | 48 | 2 |
Semaphore |
17.67 | 0 | 0 |
SemaphoreChan |
24.09 | 0 | 0 |
Results are a local baseline only. They vary by CPU, operating system, Go version, workload, and contention level.
Tests and linting
Run the test suite with:
go test ./...
Format and lint locally with:
golangci-lint fmt
golangci-lint run
GitHub Actions runs tests and golangci-lint on every push and pull request.
License
This project is distributed under the GPL-2.0 license.
Documentation
¶
Overview ¶
Package advsync provides keyed mutexes, read/write mutexes, and semaphores for coordinating concurrent Go code.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type NamedMutex ¶
type NamedMutex[K comparable] struct { // contains filtered or unexported fields }
NamedMutex provides an independent mutex for each key.
func NewNamedMutex ¶
func NewNamedMutex[K comparable]() *NamedMutex[K]
NewNamedMutex creates an empty keyed mutex collection.
func (*NamedMutex[K]) Lock ¶
func (nm *NamedMutex[K]) Lock(slug K)
Lock acquires the mutex associated with slug.
Parameters:
- slug: key identifying the mutex to acquire.
func (*NamedMutex[K]) Unlock ¶
func (nm *NamedMutex[K]) Unlock(slug K)
Unlock releases the mutex associated with slug.
Parameters:
- slug: key identifying the mutex to release.
func (*NamedMutex[K]) UnlockSafe ¶
func (nm *NamedMutex[K]) UnlockSafe(slug K) bool
UnlockSafe releases the mutex associated with slug when it appears locked.
Parameters:
- slug: key identifying the mutex to release.
Returns:
- bool: true when the mutex was released; false when it was not locked.
type NamedMutexSM ¶
type NamedMutexSM[K comparable] struct { // contains filtered or unexported fields }
NamedMutexSM provides an independent mutex for each key using xsync.Map.
func NewNamedMutexSM ¶
func NewNamedMutexSM[K comparable]() NamedMutexSM[K]
NewNamedMutexSM creates an empty keyed mutex collection.
func (*NamedMutexSM[K]) Lock ¶
func (nm *NamedMutexSM[K]) Lock(slug K)
Lock acquires the mutex associated with slug.
Parameters:
- slug: key identifying the mutex to acquire.
func (*NamedMutexSM[K]) Unlock ¶
func (nm *NamedMutexSM[K]) Unlock(slug K)
Unlock releases the mutex associated with slug.
Parameters:
- slug: key identifying the mutex to release.
func (*NamedMutexSM[K]) UnlockSafe ¶
func (nm *NamedMutexSM[K]) UnlockSafe(slug K) bool
UnlockSafe releases the mutex associated with slug when it appears locked.
Parameters:
- slug: key identifying the mutex to release.
Returns:
- bool: true when the mutex was released; false when it was not locked.
type NamedRWMutex ¶
type NamedRWMutex[K comparable] struct { // contains filtered or unexported fields }
NamedRWMutex provides an independent read/write mutex for each key.
func NewNamedRWMutex ¶
func NewNamedRWMutex[K comparable]() *NamedRWMutex[K]
NewNamedRWMutex creates an empty keyed read/write mutex collection.
func (*NamedRWMutex[K]) Lock ¶
func (nm *NamedRWMutex[K]) Lock(slug K)
Lock acquires the write lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to acquire.
func (*NamedRWMutex[K]) RLock ¶
func (nm *NamedRWMutex[K]) RLock(slug K)
RLock acquires a read lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to acquire.
func (*NamedRWMutex[K]) RUnlock ¶
func (nm *NamedRWMutex[K]) RUnlock(slug K)
RUnlock releases a read lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to release.
func (*NamedRWMutex[K]) RUnlockSafe ¶
func (nm *NamedRWMutex[K]) RUnlockSafe(slug K) bool
RUnlockSafe releases a read lock associated with slug when one is held.
Parameters:
- slug: key identifying the read/write mutex to release.
Returns:
- bool: true when a read lock was released; false when no reader was present.
func (*NamedRWMutex[K]) Unlock ¶
func (nm *NamedRWMutex[K]) Unlock(slug K)
Unlock releases the write lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to release.
func (*NamedRWMutex[K]) UnlockSafe ¶
func (nm *NamedRWMutex[K]) UnlockSafe(slug K) bool
UnlockSafe releases the write lock associated with slug when it appears locked.
Parameters:
- slug: key identifying the read/write mutex to release.
Returns:
- bool: true when the write lock was released; false when it was not locked.
type NamedRWMutexSM ¶
type NamedRWMutexSM[K comparable] struct { // contains filtered or unexported fields }
NamedRWMutexSM provides an independent read/write mutex for each key using xsync.Map.
func NewNamedRWMutexSM ¶
func NewNamedRWMutexSM[K comparable]() NamedRWMutexSM[K]
NewNamedRWMutexSM creates an empty keyed read/write mutex collection.
func (*NamedRWMutexSM[K]) Lock ¶
func (nm *NamedRWMutexSM[K]) Lock(slug K)
Lock acquires the write lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to acquire.
func (*NamedRWMutexSM[K]) RLock ¶
func (nm *NamedRWMutexSM[K]) RLock(slug K)
RLock acquires a read lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to acquire.
func (*NamedRWMutexSM[K]) RUnlock ¶
func (nm *NamedRWMutexSM[K]) RUnlock(slug K)
RUnlock releases a read lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to release.
func (*NamedRWMutexSM[K]) RUnlockSafe ¶
func (nm *NamedRWMutexSM[K]) RUnlockSafe(slug K) bool
RUnlockSafe releases a read lock associated with slug when one is held.
Parameters:
- slug: key identifying the read/write mutex to release.
Returns:
- bool: true when a read lock was released; false when no reader was present.
func (*NamedRWMutexSM[K]) Unlock ¶
func (nm *NamedRWMutexSM[K]) Unlock(slug K)
Unlock releases the write lock associated with slug.
Parameters:
- slug: key identifying the read/write mutex to release.
func (*NamedRWMutexSM[K]) UnlockSafe ¶
func (nm *NamedRWMutexSM[K]) UnlockSafe(slug K) bool
UnlockSafe releases the write lock associated with slug when it appears locked.
Parameters:
- slug: key identifying the read/write mutex to release.
Returns:
- bool: true when the write lock was released; false when it was not locked.
type NamedSemaphore ¶
type NamedSemaphore[K comparable] struct { // contains filtered or unexported fields }
NamedSemaphore provides an independent Semaphore for each key.
func NewNamedSemaphore ¶
func NewNamedSemaphore[K comparable](maxCount uint) *NamedSemaphore[K]
NewNamedSemaphore creates a keyed semaphore collection with maxCount permits per key.
Parameters:
- maxCount: maximum simultaneous acquisitions for each key.
func (*NamedSemaphore[K]) Acquire ¶
func (nm *NamedSemaphore[K]) Acquire(slug K)
Acquire waits for and acquires a permit from the semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to acquire.
func (*NamedSemaphore[K]) Release ¶
func (nm *NamedSemaphore[K]) Release(slug K) error
Release releases one acquisition for the semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to release.
Returns:
- error: an error when no matching acquisition exists.
type NamedSemaphoreChan ¶
type NamedSemaphoreChan[K comparable] struct { // contains filtered or unexported fields }
NamedSemaphoreChan provides an independent channel-based semaphore for each key.
func NewNamedSemaphoreChan ¶
func NewNamedSemaphoreChan[K comparable](maxCount uint) *NamedSemaphoreChan[K]
NewNamedSemaphoreChan creates a keyed channel-based semaphore collection.
Parameters:
- maxCount: maximum simultaneous acquisitions for each key.
func (*NamedSemaphoreChan[K]) Acquire ¶
func (nm *NamedSemaphoreChan[K]) Acquire(slug K)
Acquire waits for and acquires a permit from the semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to acquire.
func (*NamedSemaphoreChan[K]) Release ¶
func (nm *NamedSemaphoreChan[K]) Release(slug K)
Release releases one acquisition for the channel-based semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to release.
type NamedSemaphoreChanSM ¶
type NamedSemaphoreChanSM[K comparable] struct { // contains filtered or unexported fields }
NamedSemaphoreChanSM provides a channel-based semaphore for each key using xsync.Map.
func NewNamedSemaphoreChanSM ¶
func NewNamedSemaphoreChanSM[K comparable](maxCount uint) *NamedSemaphoreChanSM[K]
NewNamedSemaphoreChanSM creates a keyed channel-based semaphore collection.
Parameters:
- maxCount: maximum simultaneous acquisitions for each key.
func (*NamedSemaphoreChanSM[K]) Acquire ¶
func (nm *NamedSemaphoreChanSM[K]) Acquire(slug K)
Acquire waits for and acquires a permit from the semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to acquire.
func (*NamedSemaphoreChanSM[K]) Release ¶
func (nm *NamedSemaphoreChanSM[K]) Release(slug K)
Release releases one acquisition for the channel-based semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to release.
type NamedSemaphoreSM ¶
type NamedSemaphoreSM[K comparable] struct { // contains filtered or unexported fields }
NamedSemaphoreSM provides an independent Semaphore for each key using xsync.Map.
func NewNamedSemaphoreSM ¶
func NewNamedSemaphoreSM[K comparable](maxCount uint) *NamedSemaphoreSM[K]
NewNamedSemaphoreSM creates a keyed semaphore collection with maxCount permits per key.
Parameters:
- maxCount: maximum simultaneous acquisitions for each key.
func (*NamedSemaphoreSM[K]) Acquire ¶
func (nm *NamedSemaphoreSM[K]) Acquire(slug K)
Acquire waits for and acquires a permit from the semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to acquire.
func (*NamedSemaphoreSM[K]) Release ¶
func (nm *NamedSemaphoreSM[K]) Release(slug K) error
Release releases one acquisition for the semaphore associated with slug.
Parameters:
- slug: key identifying the semaphore to release.
Returns:
- error: an error when no matching acquisition exists.
type Semaphore ¶
type Semaphore struct {
// contains filtered or unexported fields
}
Semaphore is a counting semaphore implemented with sync.Cond.
func NewSemaphore ¶
NewSemaphore creates a Semaphore with at most maxCount concurrent acquisitions.
Parameters:
- maxCount: maximum number of acquired permits.
type SemaphoreChan ¶
type SemaphoreChan struct {
// contains filtered or unexported fields
}
SemaphoreChan is a counting semaphore implemented with a channel.
func NewSemaphoreChan ¶
func NewSemaphoreChan(maxCount uint) *SemaphoreChan
NewSemaphoreChan creates a SemaphoreChan with at most maxCount concurrent acquisitions.
Parameters:
- maxCount: maximum number of acquired permits.
func (*SemaphoreChan) Acquire ¶
func (s *SemaphoreChan) Acquire()
Acquire waits until a permit is available and then acquires it.
func (*SemaphoreChan) Close ¶
func (s *SemaphoreChan) Close()
Close closes the underlying channel.
Cases:
- Do not call Close while another goroutine can acquire or release a permit.
func (*SemaphoreChan) Release ¶
func (s *SemaphoreChan) Release()
Release releases one acquired permit.
Source Files