syncs

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.

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.

    swg := syncs.NewSizedGroup(5) // wait group with max size=5
     for i :=0; i<10; i++ {
        swg.Go(fn func(){
            doThings() // 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.

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() error { // Go here could be blocked if trying to run >5 at the same time 
           err := doThings()     // only 5 of these will run in parallel
           return err
        })
    }
    err := ewg.Wait()

Documentation

Index

• func NewSemaphore(capacity int) sync.Locker
• type ESGOption
  • func Context(ctx context.Context) ESGOption
  • func Preemptive() ESGOption
  • func TermOnErr() ESGOption
• type ErrSizedGroup
  • func NewErrSizedGroup(size int, options ...ESGOption) ErrSizedGroup
• type SizedGroup
  • func NewSizedGroup(size int) SizedGroup

Examples

• SizedGroup (Go)

Functions

func NewSemaphore

func NewSemaphore(capacity int) sync.Locker

NewSemaphore makes Semaphore with given capacity

Types

type ESGOption

type ESGOption func(esg *errSizedGroup) error

ESGOption functional option type

func Context

func Context(ctx context.Context) ESGOption

Context passes ctx and makes it cancelable

func Preemptive

func Preemptive() ESGOption

Preemptive sets locking mode preventing spawning waiting goroutine. May cause Go call to block!

func TermOnErr

func TermOnErr() ESGOption

TermOnErr prevents new goroutines to start after first error

type ErrSizedGroup

type ErrSizedGroup interface {
	Go(fn func() error)
	Wait() error
}

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

func NewErrSizedGroup

func NewErrSizedGroup(size int, options ...ESGOption) 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.

type SizedGroup

type SizedGroup interface {
	Go(fn func())
	Wait()
}

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() { // 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) SizedGroup

NewSizedGroup makes wait group with limited size alive goroutines