README
¶
Syncs - additional synchronization primitives
Package syncs provides additional synchronization primitives.
Install and update
go get -u github.com/go-pkgz/syncs
Details
Semaphore
Implements sync.Locker interface but for given capacity, thread safe. Lock increases count and Unlock - decreases. Unlock on 0 count will be blocked.
sema := syncs.NewSemaphore(10) // make semaphore with 10 initial capacity
for i :=0; i<10; i++ {
sema.Lock() // all 10 locks will pass, i.w. won't lock
}
sema.Lock() // this is 11 - will lock for real
// in some other place/goroutine
sema.Unlock() // decrease semaphore counter
SizedGroup
Mix semaphore and WaitGroup to provide sized waiting group. The result is a wait group allowing limited number of goroutine to run in parallel.
By default the locking happens inside of goroutine, i.e. every call will be non-blocked, but some goroutines may wait if semaphore locked. It means - technically it doesn't limit number of goroutines, but rather number of running (active) goroutines.
In order to block goroutines from even starting use Preemptive option (see below).
swg := syncs.NewSizedGroup(5) // wait group with max size=5
for i :=0; i<10; i++ {
swg.Go(fn func(ctx context.Context){
doThings(ctx) // only 5 of these will run in parallel
})
}
swg.Wait()
ErrSizedGroup
Sized error group is a SizedGroup with error control. Works the same as errgrp.Group, i.e. returns first error. Can work as regular errgrp.Group or with early termination. Thread safe.
Supports both in-goroutine-wait via NewErrSizedGroup as well as outside of goroutine wait with Preemptive option. Another options are TermOnErr which will skip (won't start) all other goroutines if any error returned, and Context for early termination/timeouts.
Important! With Preemptive Go call can block. In case if maximum size reached the call will wait till number of running goroutines
dropped under max. This way we not only limiting number of running goroutines but also number of waiting goroutines.
ewg := syncs.NewErrSizedGroup(5, syncs.Preemptive) // error wait group with max size=5, don't try to start more if any error happened
for i :=0; i<10; i++ {
ewg.Go(fn func(ctx context.Context) error { // Go here could be blocked if trying to run >5 at the same time
err := doThings(ctx) // only 5 of these will run in parallel
return err
})
}
err := ewg.Wait()
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewSemaphore ¶
NewSemaphore makes Semaphore with given capacity
func Preemptive ¶
func Preemptive(o *options)
Preemptive sets locking mode preventing spawning waiting goroutine. May cause Go call to block!
Types ¶
type ErrSizedGroup ¶
type ErrSizedGroup struct {
// contains filtered or unexported fields
}
ErrSizedGroup is a SizedGroup with error control. Works the same as errgrp.Group, i.e. returns first error. Can work as regular errgrp.Group or with early termination. Thread safe. ErrSizedGroup interface enforces constructor usage and doesn't allow direct creation of errSizedGroup
Example (Go) ¶
illustrates the use of a SizedGroup for concurrent, limited execution of goroutines.
// create sized waiting group allowing maximum 10 goroutines
grp := NewErrSizedGroup(10)
var c uint32
for i := 0; i < 1000; i++ {
// Go call is non-blocking, like regular go statement
grp.Go(func() error {
// do some work in 10 goroutines in parallel
atomic.AddUint32(&c, 1)
time.Sleep(10 * time.Millisecond)
return nil
})
}
// Note: grp.Go acts like go command - never blocks. This code will be executed right away
log.Print("all 1000 jobs submitted")
// wait for completion
if err := grp.Wait(); err != nil {
panic(err)
}
func NewErrSizedGroup ¶
func NewErrSizedGroup(size int, options ...GroupOption) *ErrSizedGroup
NewErrSizedGroup makes wait group with limited size alive goroutines. By default all goroutines will be started but will wait inside. For limited number of goroutines use Preemptive() options. TermOnErr will skip (won't start) all other goroutines if any error returned.
func (*ErrSizedGroup) Go ¶
func (g *ErrSizedGroup) Go(f func() error)
Go calls the given function in a new goroutine. The first call to return a non-nil error cancels the group if termOnError; its error will be returned by Wait. If no termOnError all errors will be collected in multierror.
func (*ErrSizedGroup) Wait ¶
func (g *ErrSizedGroup) Wait() error
Wait blocks until all function calls from the Go method have returned, then returns all errors (if any) wrapped with multierror from them.
type GroupOption ¶
type GroupOption func(o *options)
GroupOption functional option type
func Context ¶
func Context(ctx context.Context) GroupOption
Context passes ctx and makes it cancelable
type SizedGroup ¶
type SizedGroup struct {
// contains filtered or unexported fields
}
SizedGroup has the same role as WaitingGroup but adds a limit of the amount of goroutines started concurrently. Uses similar Go() scheduling as errgrp.Group, thread safe. SizedGroup interface enforces constructor usage and doesn't allow direct creation of sizedGroup
Example (Go) ¶
illustrates the use of a SizedGroup for concurrent, limited execution of goroutines.
grp := NewSizedGroup(10) // create sized waiting group allowing maximum 10 goroutines
var c uint32
for i := 0; i < 1000; i++ {
grp.Go(func(ctx context.Context) { // Go call is non-blocking, like regular go statement
// do some work in 10 goroutines in parallel
atomic.AddUint32(&c, 1)
time.Sleep(10 * time.Millisecond)
})
}
// Note: grp.Go acts like go command - never blocks. This code will be executed right away
log.Print("all 1000 jobs submitted")
grp.Wait() // wait for completion
func NewSizedGroup ¶
func NewSizedGroup(size int, opts ...GroupOption) *SizedGroup
NewSizedGroup makes wait group with limited size alive goroutines
func (*SizedGroup) Go ¶
func (g *SizedGroup) Go(fn func(ctx context.Context))
Go calls the given function in a new goroutine. Every call will be unblocked, but some goroutines may wait if semaphore locked.
func (*SizedGroup) Wait ¶
func (g *SizedGroup) Wait()
Wait blocks until the SizedGroup counter is zero. See sync.WaitGroup documentation for more information.
Source Files