README
¶
TryMutex
TryMutex is another synchronization primitive that additionaly to standard Lock and Unlock provides TryLock and TryLockTimeout methods.
- TryLock - tries to acquire lock returning true on success or false if failed.
- TryLockTimeout - tries to acquire a lock during specified time interval return false if time is out.
NamedMutex
Named mutex is a syncroniation primitive that acquires lock based on name. Primary usecase for myself is a lazy instantiation of objects based on name that may take significant amount of time.
The following set of methods is available:
- Lock(name) - acquire lock by name.
- Unlock(name) - release lock by name.
- TryLock(name) - return true if lock acquired, otherwise false.
- TryLockTimeout(name, timeout) - tries to acquire lock for a certain amount of time. Returns false if timeouts.
Semaphore
Semaphore is a standard semaphore implementation that uses channel as a synchronization point.
The following set of methods is available:
- Acquire - acquire lock.
- Release - releases lock.
- TryAcquire - tries to acqure lock returning true/false in case of success of failure respectively.
- TryAcqureTimeout - the same as TryAcquire, however, timeout can be provided.
- Value - return number of currently holding semaphores.
OnceMutex
Mutex that can be acquired only once. Successful lock will return true. All concurrent locks will block and return false when mutex is unlocked.
NamedOnceMutex
A named set of OnceMutex. Can be used to update local cache of data identified by some key to avoid many concurrent request for the same data if data is not in the cache yet.
ControlWaitGroup
A controlled goroutine executor that can limit the number concurrently running goroutines. Can help to solve a resource exhaustion problem.
Documentation
¶
Overview ¶
nsync package provides a set of primitives that are not provided by standard Go library.
NamedMutex - a map of dynamically created mutexes by a referred name.
OnceMutex - very similar to sync.Once, however, it is a mutex not a function wrapper.
NamedOnceMutex - a map of dynamically created mutexes that can be acquired only once. However, once mutex unlocked it is removed from the map. So, next attempt to acquire this mutex will succeed.
Semaphore - a semaphore primitive that can be acquired limited number of times.
TryMutex - A mutex that provide ability to set a timeout to acquire a lock.
ControlWaitGroup - a controlled goroutine executor that can limit the number concurrently running goroutines. Can help to solve a resource exhaustion problem.
SyncFlag - an atomic flag that is wrapped by mutex. Mutex can be set/unset separately to prevent the flag from being set/unset.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ControlWaitGroup ¶
type ControlWaitGroup struct {
// contains filtered or unexported fields
}
ControlWaitGroup is a combination of the WaitGroup and Semaphore primitives to run goroutines. WaitGroup is used to insure all tasks are complete, Semaphore server a lock job to limit a number of concurrently running goroutines. Go is well known for its capabilities to run tens of thousands of goroutines, however, it is also very easy to exceed available system resources such as connections, opened files, etc. Thus, ControlWaitGroup fits well to limit the number of running goroutines.
func NewControlWaitGroup ¶
func NewControlWaitGroup(poolSize int) *ControlWaitGroup
NewControlWaitGroup returns new instance of ControlWaitGroup
func (*ControlWaitGroup) Abort ¶
func (cwg *ControlWaitGroup) Abort()
Abort interrupts execution of any pending task that is blocked by semaphore.
func (*ControlWaitGroup) Do ¶
func (cwg *ControlWaitGroup) Do(userFunc func()) bool
Do runs user defined function with no interface. all parameters passed to the required call should be provided withing a function closure.
func (*ControlWaitGroup) Wait ¶
func (cwg *ControlWaitGroup) Wait()
Wait blocks until all goroutines finish their work.
func (*ControlWaitGroup) Waiting ¶
func (cwg *ControlWaitGroup) Waiting() int
Waiting is a number of the currently scheduled, but not running goroutines. This value is highly dynamic so it only make sense to use it for logging purposes.
func (*ControlWaitGroup) Working ¶
func (cwg *ControlWaitGroup) Working() int
Working is a number of the currently running goroutines. This value is highly dynamic so it only make sense to use it for logging purposes.
type NamedMutex ¶
type NamedMutex struct {
// contains filtered or unexported fields
}
NamedMutex acquires a lock based on a user defined name. Can be used in factories which produce singleton objects depending on the name. For example: queue name, user name, etc. Locks are based on channels, so an additional TryLock has been introduced.
func NewNamedMutex ¶
func NewNamedMutex() *NamedMutex
NewNamedMutex makes a new named mutex instance.
func (*NamedMutex) Lock ¶
func (nm *NamedMutex) Lock(name string)
Lock acquires the lock. On the first lock attempt a new channel is automatically created.
func (*NamedMutex) TryLock ¶
func (nm *NamedMutex) TryLock(name string) bool
TryLock tries to acquires the lock returning true on success. On the first lock attempt a new channel is automatically created.
func (*NamedMutex) TryLockTimeout ¶
func (nm *NamedMutex) TryLockTimeout(name string, timeout time.Duration) bool
TryLockTimeout tries to acquires the lock returning true on success. Attempt to acquire the lock will timeout after the caller defined interval. On the first lock attempt a new channel is automatically created.
func (*NamedMutex) Unlock ¶
func (nm *NamedMutex) Unlock(name string)
Unlock releases the lock. If lock hasn't been acquired function will panic.
type NamedOnceMutex ¶
type NamedOnceMutex struct {
// contains filtered or unexported fields
}
NamedOnceMutex is a map of dynamically created mutexes by provided id. First attempt to lock by id will create a new mutex and acquire a lock. All other concurrent attempts will block waiting mutex to be unlocked for the same id. Once mutex unlocked, all other lock attempts will return false for the same instance of mutex. Unlocked mutex is discarded. Next attempt to acquire a lock for the same id will succeed. Such behaviour may be used to refresh a local cache of data identified by some key avoiding concurrent request to receive a refreshed value for the same key.
func NewNamedOnceMutex ¶
func NewNamedOnceMutex() *NamedOnceMutex
NewNamedOnceMutex returns an instance of NamedOnceMutex.
func (*NamedOnceMutex) Lock ¶
func (nom *NamedOnceMutex) Lock(useMutexKey interface{}) bool
Lock try to acquire a lock for provided id. If attempt is successful, true is returned If lock is already acquired by something else it will block until mutex is unlocked returning false.
func (*NamedOnceMutex) Unlock ¶
func (nom *NamedOnceMutex) Unlock(useMutexKey interface{})
Unlock unlocks the locked mutex. Used mutex will be discarded.
type OnceMutex ¶
type OnceMutex struct {
// contains filtered or unexported fields
}
OnceMutex is a mutex that can be locked only once. Lock operation returns true if mutex has been successfully locked. Any other concurrent attempts will block until mutex is unlocked. However, any other attempts to grab a lock will return false.
type Semaphore ¶
type Semaphore struct {
// contains filtered or unexported fields
}
Semaphore implementation uses built in channel using 0 size struct values.
func NewSemaphore ¶
NewSemaphore returns an instance of a semaphore.
func (*Semaphore) Acquire ¶
func (s *Semaphore) Acquire()
Acquire tries to acquire semaphore lock. If no luck it will block.
func (*Semaphore) Release ¶
func (s *Semaphore) Release()
Release releases acquired semaphore. If semaphore is not acquired it will panic.
func (*Semaphore) TryAcquire ¶
TryAcquire tries to acquire semaphore. Returns true/false if success/failure accordingly.
func (*Semaphore) TryAcquireTimeout ¶
TryAcquireTimeout tries to acquire semaphore for a specified time interval. Returns true/false if success/failure accordingly.
type SyncFlag ¶
type TryMutex ¶
type TryMutex struct {
// contains filtered or unexported fields
}
TryMutex is another implementation to the lock primitives providing additional way to acquire locks.
func (TryMutex) TryLockTimeout ¶
TryLockTimeout tries to acquires the lock returning true on success. Attempt to acquire the lock will timeout after the caller defined interval.
Source Files