/ants

๐Ÿœ๐Ÿœ๐Ÿœ ants is the most powerful and reliable pooling solution for Go.

Primary LanguageGoMIT LicenseMIT

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 the capacity of the pool dynamically, releasing the pool, rebooting the 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

๐Ÿ’ก 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 imagine 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)
	if sum != 499500 {
		panic("the final result is wrong!!!")
	}

	// Use the MultiPool and set the capacity of the 10 goroutine pools to unlimited.
	// If you use -1 as the pool size parameter, the size will be unlimited.
	// There are two load-balancing algorithms for pools: ants.RoundRobin and ants.LeastTasks.
	mp, _ := ants.NewMultiPool(10, -1, ants.RoundRobin)
	defer mp.ReleaseTimeout(5 * time.Second)
	for i := 0; i < runTimes; i++ {
		wg.Add(1)
		_ = mp.Submit(syncCalculateSum)
	}
	wg.Wait()
	fmt.Printf("running goroutines: %d\n", mp.Running())
	fmt.Printf("finish all tasks.\n")

	// Use the MultiPoolFunc and set the capacity of 10 goroutine pools to (runTimes/10).
	mpf, _ := ants.NewMultiPoolWithFunc(10, runTimes/10, func(i interface{}) {
		myFunc(i)
		wg.Done()
	}, ants.LeastTasks)
	defer mpf.ReleaseTimeout(5 * time.Second)
	for i := 0; i < runTimes; i++ {
		wg.Add(1)
		_ = mpf.Invoke(int32(i))
	}
	wg.Wait()
	fmt.Printf("running goroutines: %d\n", mpf.Running())
	fmt.Printf("finish all tasks, result is %d\n", sum)
	if sum != 499500*2 {
		panic("the final result is wrong!!!")
	}
}

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 the 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 the pool. You can invoke the NewPool method to instantiate a pool with a given capacity, as follows:

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 contention 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 the memory of the goroutine queue in the 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.

๐Ÿ‘ Contributors

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

๐Ÿ“„ License

The source code in ants is available under the MIT License.

๐Ÿ“š Relevant Articles

๐Ÿ–ฅ Use cases

business corporations

Trusted by the following corporations/organizations.

If you're also using ants in production, please help us enrich this list by opening a pull request.

open-source software

The open-source projects below do concurrent programming with the help of ants.

  • gnet: A high-performance, lightweight, non-blocking, event-driven networking framework written in pure Go.
  • milvus: An open-source vector database for scalable similarity search and AI applications.
  • nps: A lightweight, high-performance, powerful intranet penetration proxy server, with a powerful web management terminal.
  • siyuan: SiYuan is a local-first personal knowledge management system that supports complete offline use, as well as end-to-end encrypted synchronization.
  • 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.
  • teler: Real-time HTTP Intrusion Detection.
  • 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.
  • matrixone: MatrixOne is a future-oriented hyper-converged cloud and edge native DBMS that supports transactional, analytical, and streaming workloads with a simplified and distributed database engine, across multiple data centers, clouds, edges and other heterogeneous infrastructures.
  • bk-bcs: BlueKing Container Service (BCS, same below) is a container management and orchestration platform for the micro-services under the BlueKing ecosystem.
  • trueblocks-core: TrueBlocks improves access to blockchain data for any EVM-compatible chain (particularly Ethereum mainnet) while remaining entirely local.
  • openGemini: openGemini is an open-source,cloud-native time-series database(TSDB) that can be widely used in IoT, Internet of Vehicles(IoV), O&M monitoring, and industrial Internet scenarios.
  • AdGuardDNS: AdGuard DNS is an alternative solution for tracker blocking, privacy protection, and parental control.
  • WatchAD2.0: WatchAD2.0 ๆ˜ฏ 360 ไฟกๆฏๅฎ‰ๅ…จไธญๅฟƒๅผ€ๅ‘็š„ไธ€ๆฌพ้’ˆๅฏนๅŸŸๅฎ‰ๅ…จ็š„ๆ—ฅๅฟ—ๅˆ†ๆžไธŽ็›‘ๆŽง็ณป็ปŸ๏ผŒๅฎƒๅฏไปฅๆ”ถ้›†ๆ‰€ๆœ‰ๅŸŸๆŽงไธŠ็š„ไบ‹ไปถๆ—ฅๅฟ—ใ€็ฝ‘็ปœๆต้‡๏ผŒ้€š่ฟ‡็‰นๅพๅŒน้…ใ€ๅ่ฎฎๅˆ†ๆžใ€ๅŽ†ๅฒ่กŒไธบใ€ๆ•ๆ„Ÿๆ“ไฝœๅ’Œ่œœ็ฝ่ดฆๆˆท็ญ‰ๆ–นๅผๆฅๆฃ€ๆต‹ๅ„็งๅทฒ็ŸฅไธŽๆœช็Ÿฅๅจ่ƒ๏ผŒๅŠŸ่ƒฝ่ฆ†็›–ไบ†ๅคง้ƒจๅˆ†็›ฎๅ‰็š„ๅธธ่งๅ†…็ฝ‘ๅŸŸๆธ—้€ๆ‰‹ๆณ•ใ€‚
  • vanus: Vanus is a Serverless, event streaming system with processing capabilities. It easily connects SaaS, Cloud Services, and Databases to help users build next-gen Event-driven Applications.
  • trpc-go: A pluggable, high-performance RPC framework written in Golang.
  • motan-go: a remote procedure call (RPC) framework for the rapid development of high-performance distributed services.

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.

        

๐Ÿ”‹ Sponsorship