process

README

process - goroutines as contained processes

Simple fork and join of goroutines - easy to use; no fuss.

Puts the 'P' of CSP back into Go.

All it does is handle the join when a group of goroutines terminate. Internally, a sync.WaitGroup is administered for you. There's not much to it but it makes your job easier.

Installation

go get -u github.com/rickb777/process

How To

Just create a new group then tell some functions to Go:

	processes := process.NewGroup()
	processes.Go(func() {
		...  some work, just a normal goroutine function
	})
	processes.Go(func() {
		...  some other work
	})
	processes.Join()

The Join() method does not terminate until all the sub-processes have terminated. In other words, the code that follows has to wait until then.

The second way to use process groups is to start a pool of several identical goroutines using GoN:

	processes := process.NewGroup()
	processes.GoN(3, func() {
		...  some work, just a normal goroutine function
	})
	processes.Join()

You can of course mix Go and GoN in the same process group:

	processes := process.NewGroup()
	processes.GoN(3, func() {
		...  some work, just a normal goroutine function
	})
	processes.Go(func() {
		...  some other work
	})
	processes.Join()

GoN1 is a variant of GoN that provides the index counter as a parameter, counting up from 1:

	processes := process.NewGroup()
	processes.GoN1(3, func(i int) {
		...  some work, just a normal goroutine function
	})
	processes.Join()

Hierarchies

A process group contains processes. These processes can also be process groups, or they can contain process groups. As long as the Join calls are positioned so that each group terminates tidily, the nesting should just work (TM).

Licence

MIT

Documentation

Overview

Package process wraps goroutines with the necessary synchronisation so that the caller can easily wait on completion.

Following the CSP practice, these goroutines are called 'processes' - the 'P' in Communicating Sequential Processes. But this term is not to be confused with other usages, especially of processes within operating systems; the latter are unrelated.

Index

• type ProcessGroup
  • func NewGroup() *ProcessGroup
  • func (pg *ProcessGroup) Go(process func())
  • func (pg *ProcessGroup) GoE(process func() error)
  • func (pg *ProcessGroup) GoN(n int, process func())
  • func (pg *ProcessGroup) GoN0(n int, process func(j int))
  • func (pg *ProcessGroup) GoN0E(n int, process func(j int) error)
  • func (pg *ProcessGroup) GoN1(n int, process func(j int))
  • func (pg *ProcessGroup) GoN1E(n int, process func(j int) error)
  • func (pg *ProcessGroup) GoNE(n int, process func() error)
  • func (pg *ProcessGroup) Join()
  • func (pg *ProcessGroup) JoinE() error

Types

type ProcessGroup

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

ProcessGroup allows a related group of processes (i.e. goroutines) - zero or more - to be launched. The parent goroutine can then wait for completion of the entire group via `Join()`.

A single parent goroutine will own each ProcessGroup. They should not be shared by more than one parent.

func NewGroup

func NewGroup() *ProcessGroup

NewGroup creates a new empty process group. Use Go and GoN to start processes (i.e. goroutines) within the group.

func (*ProcessGroup) Go

func (pg *ProcessGroup) Go(process func())

Go starts a single process (i.e. goroutine) within this group using a zero-argument function. This method can be called multiple times with different functions as needed. Use Join or JoinE to wait for all the processes to terminate.

func (*ProcessGroup) GoE

func (pg *ProcessGroup) GoE(process func() error)

GoE starts a single process (i.e. goroutine) within this group using a zero-argument function returning an optional error. This method can be called multiple times with different functions as needed. Use Join or JoinE to wait for all the processes to terminate.

func (*ProcessGroup) GoN

func (pg *ProcessGroup) GoN(n int, process func())

GoN starts n identical processes (i.e. goroutines) within this group using a zero-argument function. This method can be called several times with different functions as needed. Use Join or JoinE to wait for all the processes to terminate.

func (*ProcessGroup) GoN0

func (pg *ProcessGroup) GoN0(n int, process func(j int))

GoN0 starts n identical processes (i.e. goroutines) within this group using a one-argument function. This method can be called multiple times with different functions as needed. The process argument receives the index in the sequence, starting from zero. Use Join or JoinE to wait for all the processes to terminate.

func (*ProcessGroup) GoN0E

func (pg *ProcessGroup) GoN0E(n int, process func(j int) error)

GoN0E starts n identical processes (i.e. goroutines) within this group using a one-argument function returning an optional error. This method can be called multiple times with different functions as needed. The process argument receives the index in the sequence, starting from zero. Use Join or JoinE to wait for all the processes to terminate.

func (*ProcessGroup) GoN1

func (pg *ProcessGroup) GoN1(n int, process func(j int))

GoN1 starts n identical processes (i.e. goroutines) within this group using a one-argument function. This method can be called multiple times with different functions as needed. The process argument receives the index in the sequence, starting from one.

func (*ProcessGroup) GoN1E

func (pg *ProcessGroup) GoN1E(n int, process func(j int) error)

GoN1E starts n identical processes (i.e. goroutines) within this group using a one-argument function returning an optional error. This method can be called multiple times with different functions as needed. The process argument receives the index in the sequence, starting from one.

func (*ProcessGroup) GoNE

func (pg *ProcessGroup) GoNE(n int, process func() error)

GoNE starts n identical processes (i.e. goroutines) within this group using a zero-argument function returning an optional error. This method can be called several times with different functions as needed. Use Join or JoinE to wait for all the processes to terminate.

func (*ProcessGroup) Join

func (pg *ProcessGroup) Join()

Join is called by the parent goroutine when it wants to sit and wait for every process (goroutine) in this group to have terminated. Join will therefore block until this condition is reached.

Because the process group does not control the internal behaviour of each child process (goroutine), it has no means to guarantee that they will all terminated. So it is possible for this method to wait forever (deadlock), as a program error. It is up to the client code to prevent this by ensuring that all the child processes (goroutines) terminate cleanly.

func (*ProcessGroup) JoinE

func (pg *ProcessGroup) JoinE() error

JoinE is called by the parent goroutine when it wants to sit and wait for every process (goroutine) in this group to have terminated. JoinE will therefore block until this condition is reached.

See Join for further details.

It returns the collection of all errors that arose from the processes. If JoinE is called multiple times, only the newly-arising errors will be returned each time.