A goroutine pool for Go
[![Build Status][1]][2] [![codecov][3]][4] [![goreportcard for panjf2000/ants][5]][6] [![godoc for panjf2000/ants][7]][8] [![MIT Licence][9]][10] [中文项目说明](README_ZH.md) | [Project Tutorial](http://blog.taohuawu.club/article/42) Package ants implements a fixed goroutine pool for managing and recycling a massive number of goroutines, allowing developers to limit the number of goroutines that created by your concurrent programs. ## Features: - Automatically managing and recycling a massive number of goroutines. - Periodically clearing overdue goroutines. - Friendly interfaces: submitting tasks, getting the number of running goroutines, readjusting capacity of pool dynamically, closing pool. - Efficient in memory usage and it even achieves higher performance than unlimited goroutines in golang. ## How to install ``` sh go get -u github.com/panjf2000/ants ``` Or, using glide: ``` sh glide get github.com/panjf2000/ants ``` ## How to use If your program will generate a massive number of goroutines and you don't want them to consume a vast amount of memory, with ants, all you need to do is to import ants package and submit all your tasks to the default limited pool created when ants was imported: ``` go package main import ( "fmt" "sync" "sync/atomic" "time" "github.com/panjf2000/ants" ) var sum int32 func myFunc(i interface{}) error { n := i.(int32) atomic.AddInt32(&sum, n) fmt.Printf("run with %d\n", n) return nil } func demoFunc() error { time.Sleep(10 * time.Millisecond) fmt.Println("Hello World!") return nil } func main() { defer ants.Release() runTimes := 1000 // use the common pool var wg sync.WaitGroup for i := 0; i < runTimes; i++ { wg.Add(1) ants.Submit(func() error { demoFunc() wg.Done() return nil }) } wg.Wait() fmt.Printf("running goroutines: %d\n", ants.Running()) fmt.Printf("finish all tasks.\n") // use the pool with a function // set 10 the size of goroutine pool and 1 second for expired duration p, _ := ants.NewPoolWithFunc(10, func(i interface{}) error { myFunc(i) wg.Done() return nil }) defer p.Release() // submit tasks for i := 0; i < runTimes; i++ { wg.Add(1) p.Serve(int32(i)) } wg.Wait() fmt.Printf("running goroutines: %d\n", p.Running()) fmt.Printf("finish all tasks, result is %d\n", sum) } ``` ## Submit tasks Tasks can be submitted by calling `ants.Submit(func())` ```go ants.Submit(func() {}) ``` ## Custom limited pool Ants also supports custom limited pool. You can use the `NewPool` method to create a pool with the given capacity, as following: ``` go // set 10000 the size of goroutine pool and 1 second for expired duration p, _ := ants.NewPool(10000, 1) // submit a task p.Submit(func() {}) ``` ## Readjusting pool capacity You can change ants pool capacity at any time with `ReSize(int)`: ``` go pool.ReSize(1000) // Readjust its capacity to 1000 pool.ReSize(100000) // Readjust its capacity to 100000 ``` Don't worry about the synchronous problems in this case, this method is thread-safe. ## About sequence All the tasks submitted to ants pool will not be guaranteed to be processed in order, because those tasks distribute among a series of concurrent workers, thus those tasks are processed concurrently. ## Benchmarks ``` OS : macOS High Sierra Processor : 2.7 GHz Intel Core i5 Memory : 8 GB 1867 MHz DDR3 Go1.9 ```