ants

package module
v2.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2022 License: MIT Imports: 10 Imported by: 900

README

A goroutine pool for Go


English | 中文

📖 Introduction

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:

  • Managing and recycling a massive number of goroutines automatically
  • Purging overdue goroutines periodically
  • Abundant APIs: submitting tasks, getting the number of running goroutines, tuning capacity of pool dynamically, releasing pool, rebooting pool
  • Handle panic gracefully to prevent programs from crash
  • Efficient in memory usage and it even achieves higher performance than unlimited goroutines in Golang
  • Nonblocking mechanism

⚔️ Tested in the following Golang releases:

All releases from Go1.8.x to Go1.18.x.

💡 How ants works

Flow Diagram

ants-flowchart-en

Activity Diagrams

🧰 How to install

For ants v1

go get -u github.com/panjf2000/ants

For ants v2 (with GO111MODULE=on)

go get -u github.com/panjf2000/ants/v2

🛠 How to use

Just take a imagination that your program starts a massive number of goroutines, resulting in a huge consumption of memory. 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/v2"
)

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)
}

Functional options for ants pool

// Option represents the optional function.
type Option func(opts *Options)

// Options contains all options which will be applied when instantiating a ants pool.
type Options struct {
	// ExpiryDuration is a period for the scavenger goroutine to clean up those expired workers,
	// the scavenger scans all workers every `ExpiryDuration` and clean up those workers that haven't been
	// used for more than `ExpiryDuration`.
	ExpiryDuration time.Duration

	// PreAlloc indicates 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{})

	// Logger is the customized logger for logging info, if it is not set,
	// default standard logger from log package is used.
	Logger Logger
}

// WithOptions accepts the whole options config.
func WithOptions(options Options) Option {
	return func(opts *Options) {
		*opts = options
	}
}

// WithExpiryDuration sets up the interval time of cleaning up goroutines.
func WithExpiryDuration(expiryDuration time.Duration) Option {
	return func(opts *Options) {
		opts.ExpiryDuration = expiryDuration
	}
}

// WithPreAlloc indicates whether it should malloc for workers.
func WithPreAlloc(preAlloc bool) Option {
	return func(opts *Options) {
		opts.PreAlloc = preAlloc
	}
}

// WithMaxBlockingTasks sets up the maximum number of goroutines that are blocked when it reaches the capacity of pool.
func WithMaxBlockingTasks(maxBlockingTasks int) Option {
	return func(opts *Options) {
		opts.MaxBlockingTasks = maxBlockingTasks
	}
}

// WithNonblocking indicates that pool will return nil when there is no available workers.
func WithNonblocking(nonblocking bool) Option {
	return func(opts *Options) {
		opts.Nonblocking = nonblocking
	}
}

// WithPanicHandler sets up panic handler.
func WithPanicHandler(panicHandler func(interface{})) Option {
	return func(opts *Options) {
		opts.PanicHandler = panicHandler
	}
}

// WithLogger sets up a customized logger.
func WithLogger(logger Logger) Option {
	return func(opts *Options) {
		opts.Logger = logger
	}
}

ants.Optionscontains all optional configurations of ants pool, which allows 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 a 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 memory allocation in 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()

Reboot Pool

// A pool that has been released can be still used once you invoke the Reboot().
pool.Reboot()

⚙️ 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

In this benchmark result, 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.

  • BenchmarkGoroutine-4 represents the benchmarks with unlimited goroutines in golang.

  • BenchmarkPoolGroutine-4 represents the benchmarks with a ants pool.

Benchmarks with Pool

In above benchmark result, 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 performs 2 times faster than goroutines without pool (10M tasks) and it only consumes half the memory comparing with goroutines without pool. (both in 1M and 10M tasks)

Benchmarks with PoolWithFunc

Throughput (it is suitable for scenarios where tasks are submitted asynchronously without waiting for the final results)

100K tasks

1M tasks

10M tasks

📊 Performance Summary

In conclusion, ants performs 2~6 times faster than goroutines without a pool and the memory consumption is reduced by 10 to 20 times.

👏 Contributors

Please read our Contributing Guidelines before opening a PR and thank you to all the developers who already made contributions to ants!

📄 License

Source code in ants is available under the MIT License.

📚 Relevant Articles

🖥 Use cases

business companies

The following companies/organizations use ants in production.

                

open-source software

  • gnet: A high-performance, lightweight, non-blocking, event-driven networking framework written in pure Go.
  • nps: A lightweight, high-performance, powerful intranet penetration proxy server, with a powerful web management terminal.
  • milvus: An open-source vector database for scalable similarity search and AI applications.
  • osmedeus: A Workflow Engine for Offensive Security.
  • jitsu: An open-source Segment alternative. Fully-scriptable data ingestion engine for modern data teams. Set-up a real-time data pipeline in minutes, not days.
  • triangula: Generate high-quality triangulated and polygonal art from images.
  • bsc: A Binance Smart Chain client based on the go-ethereum fork.
  • jaeles: The Swiss Army knife for automated Web Application Testing.
  • devlake: The open-source dev data platform & dashboard for your DevOps tools.
All use cases:

If you have ants integrated into projects, feel free to open a pull request refreshing this list of use cases.

🔋 JetBrains OS licenses

ants had been being developed with GoLand under the free JetBrains Open Source license(s) granted by JetBrains s.r.o., hence I would like to express my thanks here.

💰 Backers

Support us with a monthly donation and help us continue our activities.

💎 Sponsors

Become a bronze sponsor with a monthly donation of $10 and get your logo on our README on Github.

☕️ Buy me a coffee

Please be sure to leave your name, GitHub account or other social media accounts when you donate by the following means so that I can add it to the list of donors as a token of my appreciation.

        

💵 Patrons

Patrick Othmer Jimmy ChenZhen Mai Yang 王开帅 Unger Alejandro Weng Wei

🔋 Sponsorship

Documentation

Index

Constants

View Source 
const (
	// DefaultAntsPoolSize is the default capacity for a default goroutine pool.
	DefaultAntsPoolSize = math.MaxInt32

	// DefaultCleanIntervalTime is the interval time to clean up goroutines.
	DefaultCleanIntervalTime = time.Second
)
View Source 
const (
	// OPENED represents that the pool is opened.
	OPENED = iota

	// CLOSED represents that the pool is closed.
	CLOSED
)

Variables

View Source 
var (

	// 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")

	// ErrInvalidPreAllocSize will be returned when trying to set up a negative capacity under PreAlloc mode.
	ErrInvalidPreAllocSize = errors.New("can not set up a negative capacity under PreAlloc mode")

	// ErrTimeout will be returned after the operations timed out.
	ErrTimeout = errors.New("operation timed out")
)

Functions

func Cap 

func Cap() int

Cap returns the capacity of this default pool.

func Free 

func Free() int

Free returns the available goroutines to work.

func Reboot added in v2.3.0 

func Reboot()

Reboot reboots the default pool.

func Release 

func Release()

Release Closes the default pool.

func Running 

func Running() int

Running returns the number of the currently running goroutines.

func Submit 

func Submit(task func()) error

Submit submits a task to pool.

Types

type Logger added in v2.4.0 

type Logger interface {
	// Printf must have the same semantics as log.Printf.
	Printf(format string, args ...interface{})
}

Logger is used for logging formatted messages.

type Option 

type Option func(opts *Options)

Option represents the optional function.

func WithDisablePurge added in v2.6.0 

func WithDisablePurge(disable bool) Option

WithDisablePurge indicates whether we turn off automatically purge.

func WithExpiryDuration 

func WithExpiryDuration(expiryDuration time.Duration) Option

WithExpiryDuration sets up the interval time of cleaning up goroutines.

func WithLogger added in v2.4.0 

func WithLogger(logger Logger) Option

WithLogger sets up a customized logger.

func WithMaxBlockingTasks 

func WithMaxBlockingTasks(maxBlockingTasks int) Option

WithMaxBlockingTasks sets up the maximum number of goroutines that are blocked when it reaches the capacity of pool.

func WithNonblocking 

func WithNonblocking(nonblocking bool) Option

WithNonblocking indicates that pool will return nil when there is no available workers.

func WithOptions 

func WithOptions(options Options) Option

WithOptions accepts the whole options config.

func WithPanicHandler 

func WithPanicHandler(panicHandler func(interface{})) Option

WithPanicHandler sets up panic handler.

func WithPreAlloc 

func WithPreAlloc(preAlloc bool) Option

WithPreAlloc indicates whether it should malloc for workers.

type Options 

type Options struct {
	// ExpiryDuration is a period for the scavenger goroutine to clean up those expired workers,
	// the scavenger scans all workers every `ExpiryDuration` and clean up those workers that haven't been
	// used for more than `ExpiryDuration`.
	ExpiryDuration time.Duration

	// PreAlloc indicates 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{})

	// Logger is the customized logger for logging info, if it is not set,
	// default standard logger from log package is used.
	Logger Logger

	// When DisablePurge is true, workers are not purged and are resident.
	DisablePurge bool
}

Options contains all options which will be applied when instantiating an ants pool.

type Pool 

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

Pool accepts the tasks from client, it limits the total of goroutines to a given number by recycling goroutines.

func NewPool 

func NewPool(size int, options ...Option) (*Pool, error)

NewPool generates an instance of ants pool.

func (*Pool) Cap 

func (p *Pool) Cap() int

Cap returns the capacity of this pool.

func (*Pool) Free 

func (p *Pool) Free() int

Free returns the number of available goroutines to work, -1 indicates this pool is unlimited.

func (*Pool) IsClosed added in v2.4.4 

func (p *Pool) IsClosed() bool

IsClosed indicates whether the pool is closed.

func (*Pool) Reboot added in v2.3.0 

func (p *Pool) Reboot()

Reboot reboots a closed pool.

func (*Pool) Release 

func (p *Pool) Release()

Release closes this pool and releases the worker queue.

func (*Pool) ReleaseTimeout added in v2.5.0 

func (p *Pool) ReleaseTimeout(timeout time.Duration) error

ReleaseTimeout is like Release but with a timeout, it waits all workers to exit before timing out.

func (*Pool) Running 

func (p *Pool) Running() int

Running returns the number of workers currently running.

func (*Pool) Submit 

func (p *Pool) Submit(task func()) error

Submit submits a task to this pool.

Note that you are allowed to call Pool.Submit() from the current Pool.Submit(), but what calls for special attention is that you will get blocked with the latest Pool.Submit() call once the current Pool runs out of its capacity, and to avoid this, you should instantiate a Pool with ants.WithNonblocking(true).

func (*Pool) Tune 

func (p *Pool) Tune(size int)

Tune changes the capacity of this pool, note that it is noneffective to the infinite or pre-allocation pool.

func (*Pool) Waiting added in v2.5.0 

func (p *Pool) Waiting() int

Waiting returns the number of tasks which are waiting be executed.

type PoolWithFunc 

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

PoolWithFunc accepts 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) Cap 

func (p *PoolWithFunc) Cap() int

Cap returns the capacity of this pool.

func (*PoolWithFunc) Free 

func (p *PoolWithFunc) Free() int

Free returns the number of available goroutines to work, -1 indicates this pool is unlimited.

func (*PoolWithFunc) Invoke 

func (p *PoolWithFunc) Invoke(args interface{}) error

Invoke submits a task to pool.

Note that you are allowed to call Pool.Invoke() from the current Pool.Invoke(), but what calls for special attention is that you will get blocked with the latest Pool.Invoke() call once the current Pool runs out of its capacity, and to avoid this, you should instantiate a PoolWithFunc with ants.WithNonblocking(true).

func (*PoolWithFunc) IsClosed added in v2.4.4 

func (p *PoolWithFunc) IsClosed() bool

IsClosed indicates whether the pool is closed.

func (*PoolWithFunc) Reboot added in v2.3.0 

func (p *PoolWithFunc) Reboot()

Reboot reboots a closed pool.

func (*PoolWithFunc) Release 

func (p *PoolWithFunc) Release()

Release closes this pool and releases the worker queue.

func (*PoolWithFunc) ReleaseTimeout added in v2.5.0 

func (p *PoolWithFunc) ReleaseTimeout(timeout time.Duration) error

ReleaseTimeout is like Release but with a timeout, it waits all workers to exit before timing out.

func (*PoolWithFunc) Running 

func (p *PoolWithFunc) Running() int

Running returns the number of workers currently running.

func (*PoolWithFunc) Tune 

func (p *PoolWithFunc) Tune(size int)

Tune changes the capacity of this pool, note that it is noneffective to the infinite or pre-allocation pool.

func (*PoolWithFunc) Waiting added in v2.5.0 

func (p *PoolWithFunc) Waiting() int

Waiting returns the number of tasks which are waiting be executed.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.