cyclicbarrier

README

cyclicbarrier

CyclicBarrier is a synchronizer that allows a set of goroutines to wait for each other to reach a common execution point, also called a barrier.

Inspired by Java CyclicBarrier https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/CyclicBarrier.html and C# Barrier https://msdn.microsoft.com/en-us/library/system.threading.barrier(v=vs.110).aspx

Usage

Initiate

import "github.com/marusama/cyclicbarrier"
...
b1 := cyclicbarrier.New(10) // new cyclic barrier with parties = 10
...
b2 := cyclicbarrier.NewWithAction(10, func() error { return nil }) // new cyclic barrier with parties = 10 and with defined barrier action

Await

b.Await(ctx)    // await other parties

Reset

b.Reset()       // reset the barrier

Simple example

// create a barrier for 10 parties with an action that increments counter
// this action will be called each time when all goroutines reach the barrier
cnt := 0
b := cyclicbarrier.NewWithAction(10, func() error {
    cnt++
    return nil
})

wg := sync.WaitGroup{}
for i := 0; i < 10; i++ {           // create 10 goroutines (the same count as barrier parties)
    wg.Add(1)
    go func() {
        for j := 0; j < 5; j++ {
            
            // do some hard work 5 times
            time.Sleep(100 * time.Millisecond)                     
            
            err := b.Await(context.TODO()) // ..and wait for other parties on the barrier.
                                           // Last arrived goroutine will do the barrier action
                                           // and then pass all other goroutines to the next round
            if err != nil {
                panic(err)
            }
        }
        wg.Done()
    }()
}

wg.Wait()
fmt.Println(cnt)                    // cnt = 5, it means that the barrier was passed 5 times

For more documentation see https://godoc.org/github.com/marusama/cyclicbarrier

Documentation

Overview

Package cyclicbarrier provides an implementation of Cyclic Barrier primitive.

Index

• Variables
• type CyclicBarrier
  • func New(parties int) CyclicBarrier
  • func NewWithAction(parties int, barrierAction func() error) CyclicBarrier

Variables

var (
	// ErrBrokenBarrier error used when a goroutine tries to wait upon a barrier that is in a broken state,
	// or which enters the broken state while the goroutine is waiting.
	ErrBrokenBarrier = errors.New("broken barrier")
)

Types

type CyclicBarrier

type CyclicBarrier interface {
	// Await waits until all parties have invoked await on this barrier.
	// If the barrier is reset while any goroutine is waiting, or if the barrier is broken when await is invoked,
	// or while any goroutine is waiting, then ErrBrokenBarrier is returned.
	// If any goroutine is interrupted by ctx.Done() while waiting, then all other waiting goroutines
	// will return ErrBrokenBarrier and the barrier is placed in the broken state.
	// If the current goroutine is the last goroutine to arrive, and a non-nil barrier action was supplied in the constructor,
	// then the current goroutine runs the action before allowing the other goroutines to continue.
	// If an error occurs during the barrier action then that error will be returned and the barrier is placed in the broken state.
	Await(ctx context.Context) error

	// Reset resets the barrier to its initial state.
	// If any parties are currently waiting at the barrier, they will return with a ErrBrokenBarrier.
	Reset()

	// GetNumberWaiting returns the number of parties currently waiting at the barrier.
	GetNumberWaiting() int

	// GetParties returns the number of parties required to trip this barrier.
	GetParties() int

	// IsBroken queries if this barrier is in a broken state.
	// Returns true if one or more parties broke out of this barrier due to interruption by ctx.Done() or the last reset,
	// or a barrier action failed due to an error; false otherwise.
	IsBroken() bool
}

CyclicBarrier is a synchronizer that allows a set of goroutines to wait for each other to reach a common execution point, also called a barrier. CyclicBarriers are useful in programs involving a fixed sized party of goroutines that must occasionally wait for each other. The barrier is called cyclic because it can be re-used after the waiting goroutines are released. A CyclicBarrier supports an optional Runnable command that is run once per barrier point, after the last goroutine in the party arrives, but before any goroutines are released. This barrier action is useful for updating shared-state before any of the parties continue.

func New

func New(parties int) CyclicBarrier

New initializes a new instance of the CyclicBarrier, specifying the number of parties.

func NewWithAction

func NewWithAction(parties int, barrierAction func() error) CyclicBarrier

NewWithAction initializes a new instance of the CyclicBarrier, specifying the number of parties and the barrier action.