Syncs - additional synchronization primitives¶

The syncs package offers extra synchronization primitives, such as Semaphore, SizedGroup, and ErrSizedGroup, to help manage concurrency in Go programs. With syncs package, you can efficiently manage concurrency in your Go programs using additional synchronization primitives. Use them according to your specific use-case requirements to control and limit concurrent goroutines while handling errors and early termination effectively.

Install and update¶

go get -u github.com/go-pkgz/syncs

Details¶

Semaphore¶

Semaphore implements the sync.Locker interface with an additional TryLock function and a specified capacity. It is thread-safe. The Lock function increases the count, while Unlock decreases it. When the count is 0, Unlock will block, and Lock will block until the count is greater than 0. The TryLock function will return false if locking failed (i.e. semaphore is locked) and true otherwise.

    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
    ok := sema.TryLock() // try to lock, will return false if semaphore is locked 

SizedGroup¶

SizedGroup combines Semaphore and WaitGroup to provide a wait group that allows a limited number of goroutines to run in parallel.

By default, locking happens inside the goroutine. This means every call will be non-blocking, but some goroutines may wait if the semaphore is locked. Technically, it doesn’t limit the number of goroutines but rather the number of running (active) goroutines.

To block goroutines from starting, use the Preemptive option. Important: With Preemptive, the Go call can block. If the maximum size is reached, the call will wait until the number of running goroutines drops below the maximum. This not only limits the number of running goroutines but also the number of waiting goroutines.

    swg := syncs.NewSizedGroup(5) // wait group with max size=5
    for i :=0; i<10; i++ {
        swg.Go(func(ctx context.Context){
            doThings(ctx) // only 5 of these will run in parallel
        })
    }
    swg.Wait()

Another option is Discard, which will skip (won’t start) goroutines if the semaphore is locked. In other words, if a defined number of goroutines are already running, the call will be discarded. Discard is useful when you don’t care about the results of extra goroutines; i.e., you just want to run some tasks in parallel but can allow some number of them to be ignored. This flag sets Preemptive as well, because otherwise, it doesn’t make sense.

    swg := syncs.NewSizedGroup(5, Discard) // wait group with max size=5 and discarding extra goroutines
    for i :=0; i<10; i++ {
        swg.Go(func(ctx context.Context){
            doThings(ctx) // only 5 of these will run in parallel and 5 other can be discarded
        })
    }
    swg.Wait()

ErrSizedGroup¶

ErrSizedGroup is a SizedGroup with error control. It works the same as errgrp.Group, i.e., it returns the first error. It can work as a regular errgrp.Group or with early termination. It is thread-safe.

ErrSizedGroup supports both in-goroutine-wait as well as outside of goroutine wait with Preemptive and Discard options (see above). Other options include TermOnErr, which skips (won’t start) all other goroutines if any error is returned, and Context for early termination/timeouts.

    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(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()