Repository files navigation

Tunny is a Golang library for spawning and managing a goroutine pool, allowingyou to limit work coming from any number of goroutines with a synchronous API.

A fixed goroutine pool is helpful when you have work coming from an arbitrarynumber of asynchronous sources, but a limited capacity for parallel processing.For example, when processing jobs from HTTP requests that are CPU heavy you cancreate a pool with a size that matches your CPU count.

go get github.com/Jeffail/tunny

Or, using dep:

dep ensure -add github.com/Jeffail/tunny

For most cases your heavy work can be expressed in a simplefunc(), where youcan useNewFunc. Let's see how this looks using our HTTP requests to CPU countexample:

package mainimport ("io/ioutil""net/http""runtime""github.com/Jeffail/tunny")funcmain() {numCPUs:=runtime.NumCPU()pool:=tunny.NewFunc(numCPUs,func(payloadinterface{})interface{} {varresult []byte// TODO: Something CPU heavy with payloadreturnresult})deferpool.Close()http.HandleFunc("/work",func(w http.ResponseWriter,r*http.Request) {input,err:=ioutil.ReadAll(r.Body)iferr!=nil {http.Error(w,"Internal error",http.StatusInternalServerError)}deferr.Body.Close()// Funnel this work into our pool. This call is synchronous and will// block until the job is completed.result:=pool.Process(input)w.Write(result.([]byte))})http.ListenAndServe(":8080",nil)}

Tunny also supports timeouts. You can replace theProcess call above to thefollowing:

result,err:=pool.ProcessTimed(input,time.Second*5)iferr==tunny.ErrJobTimedOut {http.Error(w,"Request timed out",http.StatusRequestTimeout)}

You can also use the context from the request (or any other context) to handle timeouts and deadlines. Simply replace theProcess call to the following:

result,err:=pool.ProcessCtx(r.Context(),input)iferr==context.DeadlineExceeded {http.Error(w,"Request timed out",http.StatusRequestTimeout)}

The size of a Tunny pool can be changed at any time withSetSize(int):

pool.SetSize(10)// 10 goroutinespool.SetSize(100)// 100 goroutines

This is safe to perform from any goroutine even if others are still processing.

Sometimes each goroutine within a Tunny pool will require its own managed state.In this case you should implementtunny.Worker, which includescalls for terminating, interrupting (in case a job times out and is no longerneeded) and blocking the next job allocation until a condition is met.

When creating a pool usingWorker types you will need to provide a constructorfunction for spawning your custom implementation:

pool:=tunny.New(poolSize,func()Worker {// TODO: Any per-goroutine state allocation here.returnnewCustomWorker()})

This allows Tunny to create and destroyWorker types cleanly when the poolsize is changed.

Backlogged jobs are not guaranteed to be processed in order. Due to the currentimplementation of channels and select blocks a stack of backlogged jobs will beprocessed as a FIFO queue. However, this behaviour is not part of the spec andshould not be relied upon.