co

README

Cogo

A package for high-level concurrency patterns, in Go.

Usage

Parallelism

Cogo offers two types of parallelism: implicit and explicit. Implicit parallelism means that Cogo will control how many goroutines are used to introduce parallelism, in contrast to explicit parallelism which gives control to the user.

Implicit Parallelism

In the following example, we use the co.ForAll function to loop over different iterators. Iterators are any value that makes sense to loop over: arrays, slices, maps, and integers. Cogo will use one goroutine per CPU core available and we cannot make any assumptions about which iteration will run on which goroutine. Calling co.ForAll will block until all iterations have finished running.

// Fill an array of integers with random values
xs := [10]int{}
co.ForAll(xs, func(i int) {
    xs[i] = rand.Intn(10)
})

// Map those random values to booleans
ys := [10]bool{}
co.ForAll(10, func(i int) {
    ys[i] = xs[i] > 5
})

In the following example, we use the co.Begin function to run distinct tasks. As before, Cogo will use one goroutine per CPU core available and map the different tasks over these goroutines. Calling co.Begin will block until all tasks have finished running.

co.Begin(
    func() {
        log.Info("[task 1] when will this print?")
    },
    func() {
        log.Info("[task 2] who knows?")
    },
    func() {
        log.Info("[task 3] implicit parallelism is great!")
    })

Explicit Parallelism

In the following example, we use the co.ParForAll function to loop over different iterators. As with implicitly parallel loops, iterators are any value that makes sense to loop over: arrays, slices, maps, and integers. Unlike implicitly parallel loops, Cogo will use one goroutine per iteration, regardless of the number of CPU cores available. Calling co.ParForAll will block until all iterations have finished running.

// Fill an array of integers with random values
xs := [10]int{}
co.ParForAll(xs, func(i int) {
    xs[i] = rand.Intn(10)
})

// Map those random values to booleans
ys := [10]bool{}
co.ParForAll(10, func(i int) {
    ys[i] = xs[i] > 5
})

In the following example, we use the co.ParBegin function to run distinct tasks. Similar to the co.ParForAll function, Cogo will use one goroutine per task. Calling co.ParBegin will block until all tasks have finished running.

co.ParBegin(
    func() {
        log.Info("[task 1] when will this print?")
    },
    func() {
        log.Info("[task 2] who knows?")
    },
    func() {
        log.Info("[task 3] explicit parallelism is great!")
    })

Documentation

Index

• func ForAll(iter interface{}, f interface{})
• func Forward(done <-chan struct{}, in interface{}, out interface{})
• func Merge(done <-chan struct{}, ins interface{}, out interface{})
• func ParBegin(fs ...func())
• func ParForAll(iter interface{}, f interface{})

Functions

func ForAll

func ForAll(iter interface{}, f interface{})

ForAll uses an iterator to execute an iterand function on each value returned by the iterator, using a background goroutine for CPU and distributing the iterands evenly across each goroutine. An iterator can be an array, a slice, a map, or an int. For arrays, and slices, the iterand function must accept an int index as the only argument. For maps, the iterand function must accept a key as the only argument. For ints, the iterand function must accept an int, in the range [0, n), as the only argument. This function blocks until all goroutines have terminated.

func Forward

func Forward(done <-chan struct{}, in interface{}, out interface{})

Forward all values from an input channels into an output channel. Forward is blocking and panics when the input channel type do no match the output channel.

func Merge

func Merge(done <-chan struct{}, ins interface{}, out interface{})

Merge multiple input channels into an output channel. Merge accepts a channel of channels as input. For each of the channel read from the channel of channels, all values are consumed and produced onto the output channel. Merge is blocking and panics when the input channel types do no match the output channel.

func ParBegin

func ParBegin(fs ...func())

ParBegin multiple functions onto background goroutines. This function blocks until all goroutines have terminated.

func ParForAll

func ParForAll(iter interface{}, f interface{})

ParForAll uses an iterator to execute an iterand function on each value returned by the iterator, using a background goroutine for each iteration. An iterator can be an array, a slice, a map, or an int. For arrays, and slices, the iterand function must accept an int index as the only argument. For maps, the iterand function must accept a key as the only argument. For ints, the iterand function must accept an int, in the range [0, n), as the only argument. This function blocks until all goroutines have terminated.