sync

README

sync

Extensions of golang sync package

Documentation

Overview

This package provides some features available in golang's sync package with some enhancements.

Once

The Once defined by this package is a stateful implementation which can be passed around to other fuctions. It adds additional features to test whether the operations have already been Done and also allows Reset. These features especially the stateful nature makes it useful at multiple places where it needs to be shared by go-routines.

Once is concurrency safe and has well defined behavior for concurrent access. See the test cases.

Index

• type FuncType
• type Once
  • func NewDefaultOnce(f FuncType, fs ...FuncType) (*Once, error)
  • func NewOnce(lazyDone bool, suppressPanic bool, verify VerifyType, f FuncType, ...) (*Once, error)
  • func (d *Once) Close()
  • func (d *Once) Do() (res bool)
  • func (d *Once) Done(block bool) bool
  • func (d *Once) Reset() bool
• type VerifyType

Types

type FuncType

type FuncType func() bool

FuncType all functions passed to Once should have this signature. i.e. they don't accept arguments and always return a bool. You need to wrap you function is it's doesn't staisfy FuncType. The return value of functions is used by Once based on VerifyType.

type Once

type Once struct {
	// contains filtered or unexported fields
}

Once defines the stateful type. Clients should use NewOnce to create objects

func NewDefaultOnce

func NewDefaultOnce(f FuncType, fs ...FuncType) (*Once, error)

NewDefaultOnce is a wrapper over NewOnce. It returns a Once object with the default options.

func NewOnce

func NewOnce(lazyDone bool, suppressPanic bool, verify VerifyType, f FuncType, fs ...FuncType) (*Once, error)

NewOnce returns a new Once object with the give options. Atleast one function needs to be given. In case of muliple functions, they are executed in the order they were passed.

Below paramether combinations will raise error:

• lazyDone = true; verify = VerifyAll / VerifyFirstRunAll / VerifyFirstExit

func (*Once) Close

func (d *Once) Close()

Close() unblocks all goroutines waiting on Done(true)

func (*Once) Do

func (d *Once) Do() (res bool)

Do function is used to execute the function/s once. When multiple goroutines try to call Do(), only one go-routine will be able to call the function/s at a time. The remaining go-routines stay blocked till the first one finishes. The go-routine which is able to successfully call the function/s will get `true` returned by Do(), all others get a false. This helps identify which call to Do() was successful if there are mulitple and the client needs to know which one worked. A lot of what Do ends up doing will depend on the different options used while crating Once.

lazyDone bool

when lazyDone = false, Do() firt sets the state as DONE and then goes on to execute the function/s. If lazyDone = false, Do() first calls function and then sets DONE. Whether DONE gets set is also dependent on Verify options.

suppressPanic bool

if suppressPanic = true, any panics from the code executed by function/s will be suppressed. When panics are suppressed, successive Do() calls may or may not trigger the function/s even if the first exection did panic. That is dependent on the value of Verify used. See the unit test cases for all possible cases

func (*Once) Done

func (d *Once) Done(block bool) bool

Done returns if the Once is in DONE state. Calls to Done() are non-blocking. Value used for lazyDone changes behavior in case of concurrent access. If Done() if called concurrently with Do() it may return true even if Do() is still executing.

Done(true) : the calling goroutines will block till the state becomes DONE or Close() is called explicitly to unblocak all goroutines

returns true or false based on whether state is DONE or not.

Done(false) : returns immediately and returns whether state is DONE or not.

func (*Once) Reset

func (d *Once) Reset() bool

Reset resets Once for reuse. It also returns if reset was actually required or not. Reset is concurrency safe. In case a Do() call is already in progress(has acquired the lock), reset will happen after Do() finishes.

type VerifyType

type VerifyType string

VerifyType decides how Do will interpret and use the return values of the functions. The default is VerifyNone i.e. return values are not considered while setting state to DONE.

const (
	VerifyNone        VerifyType = ""                  // No verification of return value/s: Default
	VerifyAll         VerifyType = "VerifyAll"         // the Once is set in DONE state only if all functions return true
	VerifyFirstRunAll VerifyType = "VerifyFirstRunAll" // the Once is set in DONE state based on first function returning true, but all functions are executed
	VerifyFirstExit   VerifyType = "VerifyFirstExit"   // Set state to DONE based on the first function that returns true. Skip execution of remaining functions
)