The highest tagged major version is
README
¶
ants
A goroutine pool for Go
Library ants implements a goroutine pool with fixed capacity, managing and recycling a massive number of goroutines, allowing developers to limit the number of goroutines in your concurrent programs.
Features:
- Automatically managing and recycling a massive number of goroutines.
- Periodically purging overdue goroutines.
- Friendly interfaces: submitting tasks, getting the number of running goroutines, tuning capacity of pool dynamically, closing pool.
- Handle panic gracefully to prevent programs from crash.
- Efficient in memory usage and it even achieves higher performance than unlimited goroutines in golang.
Tested in the following Golang versions:
- 1.8.x
- 1.9.x
- 1.10.x
- 1.11.x
- 1.12.x
How to install
go get -u github.com/panjf2000/ants
How to use
Just take a imagination that your program starts a massive number of goroutines, from which a vast amount of memory will be consumed. To mitigate that kind of situation, all you need to do is to import ants package and submit all your tasks to a default pool with fixed capacity, activated when package ants is imported:
package main
import (
"fmt"
"sync"
"sync/atomic"
"time"
"github.com/panjf2000/ants"
)
var sum int32
func myFunc(i interface{}) {
n := i.(int32)
atomic.AddInt32(&sum, n)
fmt.Printf("run with %d\n", n)
}
func demoFunc() {
time.Sleep(10 * time.Millisecond)
fmt.Println("Hello World!")
}
func main() {
defer ants.Release()
runTimes := 1000
// Use the common pool.
var wg sync.WaitGroup
syncCalculateSum := func() {
demoFunc()
wg.Done()
}
for i := 0; i < runTimes; i++ {
wg.Add(1)
_ = ants.Submit(syncCalculateSum)
}
wg.Wait()
fmt.Printf("running goroutines: %d\n", ants.Running())
fmt.Printf("finish all tasks.\n")
// Use the pool with a function,
// set 10 to the capacity of goroutine pool and 1 second for expired duration.
p, _ := ants.NewPoolWithFunc(10, func(i interface{}) {
myFunc(i)
wg.Done()
})
defer p.Release()
// Submit tasks one by one.
for i := 0; i < runTimes; i++ {
wg.Add(1)
_ = p.Invoke(int32(i))
}
wg.Wait()
fmt.Printf("running goroutines: %d\n", p.Running())
fmt.Printf("finish all tasks, result is %d\n", sum)
}
Integrate with http server
package main
import (
"io/ioutil"
"net/http"
"github.com/panjf2000/ants"
)
type Request struct {
Param []byte
Result chan []byte
}
func main() {
pool, _ := ants.NewPoolWithFunc(100000, func(payload interface{}) {
request, ok := payload.(*Request)
if !ok {
return
}
reverseParam := func(s []byte) []byte {
for i, j := 0, len(s)-1; i < j; i, j = i+1, j-1 {
s[i], s[j] = s[j], s[i]
}
return s
}(request.Param)
request.Result <- reverseParam
})
defer pool.Release()
http.HandleFunc("/reverse", func(w http.ResponseWriter, r *http.Request) {
param, err := ioutil.ReadAll(r.Body)
if err != nil {
http.Error(w, "request error", http.StatusInternalServerError)
}
defer r.Body.Close()
request := &Request{Param: param, Result: make(chan []byte)}
// Throttle the requests traffic with ants pool. This process is asynchronous and
// you can receive a result from the channel defined outside.
if err := pool.Invoke(request); err != nil {
http.Error(w, "throttle limit error", http.StatusInternalServerError)
}
w.Write(<-request.Result)
})
http.ListenAndServe(":8080", nil)
}
Functional options for ants pool
type Options struct {
// ExpiryDuration set the expired time (second) of every worker.
ExpiryDuration time.Duration
// PreAlloc indicate whether to make memory pre-allocation when initializing Pool.
PreAlloc bool
// Max number of goroutine blocking on pool.Submit.
// 0 (default value) means no such limit.
MaxBlockingTasks int
// When Nonblocking is true, Pool.Submit will never be blocked.
// ErrPoolOverload will be returned when Pool.Submit cannot be done at once.
// When Nonblocking is true, MaxBlockingTasks is inoperative.
Nonblocking bool
// PanicHandler is used to handle panics from each worker goroutine.
// if nil, panics will be thrown out again from worker goroutines.
PanicHandler func(interface{})
}
func WithOptions(options Options) Option {
return func(opts *Options) {
*opts = options
}
}
func WithExpiryDuration(expiryDuration time.Duration) Option {
return func(opts *Options) {
opts.ExpiryDuration = expiryDuration
}
}
func WithPreAlloc(preAlloc bool) Option {
return func(opts *Options) {
opts.PreAlloc = preAlloc
}
}
func WithMaxBlockingTasks(maxBlockingTasks int) Option {
return func(opts *Options) {
opts.MaxBlockingTasks = maxBlockingTasks
}
}
func WithNonblocking(nonblocking bool) Option {
return func(opts *Options) {
opts.Nonblocking = nonblocking
}
}
func WithPanicHandler(panicHandler func(interface{})) Option {
return func(opts *Options) {
opts.PanicHandler = panicHandler
}
}
ants.Optionscontains all optional configurations of ants pool, which allow you to customize the goroutine pool by invoking option functions to set up each configuration in NewPool/NewPoolWithFuncmethod.
Customize limited pool
ants also supports customizing the capacity of pool. You can invoke the NewPool method to instantiate a pool with a given capacity, as following:
// Set 10000 the size of goroutine pool
p, _ := ants.NewPool(10000)
Submit tasks
Tasks can be submitted by calling ants.Submit(func())
ants.Submit(func(){})
Tune pool capacity in runtime
You can tune the capacity of ants pool in runtime with Tune(int):
pool.Tune(1000) // Tune its capacity to 1000
pool.Tune(100000) // Tune its capacity to 100000
Don't worry about the synchronous problems in this case, the method here is thread-safe (or should be called goroutine-safe).
Pre-malloc goroutine queue in pool
ants allows you to pre-allocate memory of goroutine queue in pool, which may get a performance enhancement under some special certain circumstances such as the scenario that requires an pool with ultra-large capacity, meanwhile each task in goroutine lasts for a long time, in this case, pre-mallocing will reduce a lot of costs when re-slicing goroutine queue.
// ants will pre-malloc the whole capacity of pool when you invoke this method
p, _ := ants.NewPool(100000, ants.WithPreAlloc(true))
Release Pool
pool.Release()
About sequence
All tasks submitted to ants pool will not be guaranteed to be addressed in order, because those tasks scatter among a series of concurrent workers, thus those tasks would be executed concurrently.
Benchmarks
OS: macOS High Sierra
Processor: 2.7 GHz Intel Core i5
Memory: 8 GB 1867 MHz DDR3
Go Version: 1.9
-
BenchmarkGoroutine-4 represents the benchmarks with unlimited goroutines in golang.
-
BenchmarkPoolGroutine-4 represents the benchmarks with a
antspool.
The test data above is a basic benchmark and more detailed benchmarks are about to be uploaded later.
Benchmarks with Pool
In above benchmark picture, the first and second benchmarks performed test cases with 1M tasks and the rest of benchmarks performed test cases with 10M tasks, both in unlimited goroutines and ants pool, and the capacity of this ants goroutine-pool was limited to 50K.
As you can see, ants can up to 2x faster than goroutines without pool (10M tasks) and it only consumes half the memory comparing with goroutines without pool. (both 1M and 10M tasks)
Benchmarks with PoolWithFunc
Throughput (it is suitable for scenarios where asynchronous tasks are submitted despite of the final results)
100K tasks
1M tasks
10M tasks
Performance Summary
In conclusion, ants can up to 2x~6x faster than goroutines without a pool and the memory consumption is reduced by 10 to 20 times.
Documentation
¶
Index ¶
- Constants
- Variables
- func Cap() int
- func Free() int
- func Release()
- func Running() int
- func Submit(task func()) error
- type Option
- func WithExpiryDuration(expiryDuration time.Duration) Option
- func WithMaxBlockingTasks(maxBlockingTasks int) Option
- func WithNonblocking(nonblocking bool) Option
- func WithOptions(options Options) Option
- func WithPanicHandler(panicHandler func(interface{})) Option
- func WithPreAlloc(preAlloc bool) Option
- type Options
- type Pool
- type PoolWithFunc
Constants ¶
const ( // DEFAULT_ANTS_POOL_SIZE is the default capacity for a default goroutine pool. DEFAULT_ANTS_POOL_SIZE = math.MaxInt32 // DEFAULT_CLEAN_INTERVAL_TIME is the interval time to clean up goroutines. DEFAULT_CLEAN_INTERVAL_TIME = 1 // CLOSED represents that the pool is closed. CLOSED = 1 )
Variables ¶
var ( // ErrInvalidPoolSize will be returned when setting a negative number as pool capacity. ErrInvalidPoolSize = errors.New("invalid size for pool") // ErrLackPoolFunc will be returned when invokers don't provide function for pool. ErrLackPoolFunc = errors.New("must provide function for pool") // ErrInvalidPoolExpiry will be returned when setting a negative number as the periodic duration to purge goroutines. ErrInvalidPoolExpiry = errors.New("invalid expiry for pool") // ErrPoolClosed will be returned when submitting task to a closed pool. ErrPoolClosed = errors.New("this pool has been closed") // ErrPoolOverload will be returned when the pool is full and no workers available. ErrPoolOverload = errors.New("too many goroutines blocked on submit or Nonblocking is set") )
Functions ¶
Types ¶
type Option ¶ added in v1.3.0
type Option func(opts *Options)
func WithExpiryDuration ¶ added in v1.3.0
func WithMaxBlockingTasks ¶ added in v1.3.0
func WithNonblocking ¶ added in v1.3.0
func WithOptions ¶ added in v1.3.0
func WithPanicHandler ¶ added in v1.3.0
func WithPanicHandler(panicHandler func(interface{})) Option
func WithPreAlloc ¶ added in v1.3.0
type Options ¶ added in v1.3.0
type Options struct {
// ExpiryDuration set the expired time (second) of every worker.
ExpiryDuration time.Duration
// PreAlloc indicate whether to make memory pre-allocation when initializing Pool.
PreAlloc bool
// Max number of goroutine blocking on pool.Submit.
// 0 (default value) means no such limit.
MaxBlockingTasks int
// When Nonblocking is true, Pool.Submit will never be blocked.
// ErrPoolOverload will be returned when Pool.Submit cannot be done at once.
// When Nonblocking is true, MaxBlockingTasks is inoperative.
Nonblocking bool
// PanicHandler is used to handle panics from each worker goroutine.
// if nil, panics will be thrown out again from worker goroutines.
PanicHandler func(interface{})
}
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool accept the tasks from client, it limits the total of goroutines to a given number by recycling goroutines.
type PoolWithFunc ¶
type PoolWithFunc struct {
// contains filtered or unexported fields
}
PoolWithFunc accept the tasks from client, it limits the total of goroutines to a given number by recycling goroutines.
func NewPoolWithFunc ¶
func NewPoolWithFunc(size int, pf func(interface{}), options ...Option) (*PoolWithFunc, error)
NewPoolWithFunc generates an instance of ants pool with a specific function.
func (*PoolWithFunc) Free ¶
func (p *PoolWithFunc) Free() int
Free returns a available goroutines to work.
func (*PoolWithFunc) Invoke ¶
func (p *PoolWithFunc) Invoke(args interface{}) error
Invoke submits a task to pool.
func (*PoolWithFunc) Running ¶
func (p *PoolWithFunc) Running() int
Running returns the number of the currently running goroutines.
func (*PoolWithFunc) Tune ¶
func (p *PoolWithFunc) Tune(size int)
Tune change the capacity of this pool.
Source Files
Directories