ants

package module
v2.11.0 Latest Latest
Warning

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

 Go to latest Published: Jan 12, 2025 License: MIT Imports: 14 Imported by: 1,131

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 the capacity of the pool dynamically, releasing the pool, rebooting the pool, etc.
  • Handle panic gracefully to prevent programs from crash
  • Efficient in memory usage and it may even achieve higher performance than unlimited goroutines in Go
  • Nonblocking mechanism
  • Preallocated memory (ring buffer, optional)

💡 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

Check out the examples for basic usage.

Functional options for pool

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/NewPoolWithFunc/NewPoolWithFuncGeneric method.

Check out ants.Options and ants.Option for more details.

Customize pool capacity

ants supports customizing the capacity of the pool. You can call 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

ants.Submit(func(){})

Tune pool capacity at runtime

You can tune the capacity of ants pool at runtime with ants.Tune:

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 calling ants.NewPool.
p, _ := ants.NewPool(100000, ants.WithPreAlloc(true))

Release pool

pool.Release()

or

pool.ReleaseTimeout(time.Second * 3)

Reboot pool

// A pool that has been released can be still used after calling 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.
  • TDengine: TDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, and Industrial IoT.
  • 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: Motan is a cross-language remote procedure call(RPC) framework for rapid development of high performance distributed services. motan-go is the golang implementation of Motan.
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 has 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.

JetBrains logo.

💰 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

Documentation

Overview

Package ants implements an efficient and reliable goroutine pool for Go.

With ants, Go applications are able to limit the number of active goroutines, recycle goroutines efficiently, and reduce the memory footprint significantly. Package ants is extremely useful in the scenarios where a massive number of goroutines are created and destroyed frequently, such as highly-concurrent batch processing systems, HTTP servers, services of asynchronous tasks, etc.

Index

Examples

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

	// ErrInvalidPoolIndex will be returned when trying to retrieve a pool with an invalid index.
	ErrInvalidPoolIndex = errors.New("invalid pool index")

	// ErrInvalidLoadBalancingStrategy will be returned when trying to create a MultiPool with an invalid load-balancing strategy.
	ErrInvalidLoadBalancingStrategy = errors.New("invalid load-balancing strategy")

	// ErrInvalidMultiPoolSize  will be returned when trying to create a MultiPool with an invalid size.
	ErrInvalidMultiPoolSize = errors.New("invalid size for multiple pool")
)

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 ReleaseTimeout added in v2.8.0 

func ReleaseTimeout(timeout time.Duration) error

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

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 LoadBalancingStrategy added in v2.9.0 

type LoadBalancingStrategy int

LoadBalancingStrategy represents the type of load-balancing algorithm. 

const (
	// RoundRobin distributes task to a list of pools in rotation.
	RoundRobin LoadBalancingStrategy = 1 << (iota + 1)

	// LeastTasks always selects the pool with the least number of pending tasks.
	LeastTasks
)

type Logger added in v2.4.0 

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

Logger is used for logging formatted messages.

type MultiPool added in v2.9.0 

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

MultiPool consists of multiple pools, from which you will benefit the performance improvement on basis of the fine-grained locking that reduces the lock contention. MultiPool is a good fit for the scenario where you have a large number of tasks to submit, and you don't want the single pool to be the bottleneck.

Example 
atomic.StoreInt32(&sum, 0)
runTimes := 1000
wg.Add(runTimes)

mp, _ := ants.NewMultiPool(10, runTimes/10, ants.RoundRobin)
defer mp.ReleaseTimeout(time.Second) // nolint:errcheck

for i := 0; i < runTimes; i++ {
	j := i
	_ = mp.Submit(func() {
		incSumInt(int32(j))
	})
}
wg.Wait()

fmt.Printf("The result is %d\n", sum)

Output:

The result is 499500

func NewMultiPool added in v2.9.0 

func NewMultiPool(size, sizePerPool int, lbs LoadBalancingStrategy, options ...Option) (*MultiPool, error)

NewMultiPool instantiates a MultiPool with a size of the pool list and a size per pool, and the load-balancing strategy.

func (*MultiPool) Cap added in v2.9.0 

func (mp *MultiPool) Cap() (n int)

Cap returns the capacity of this multi-pool.

func (*MultiPool) Free added in v2.9.0 

func (mp *MultiPool) Free() (n int)

Free returns the number of available workers across all pools.

func (*MultiPool) FreeByIndex added in v2.9.0 

func (mp *MultiPool) FreeByIndex(idx int) (int, error)

FreeByIndex returns the number of available workers in the specific pool.

func (*MultiPool) IsClosed added in v2.9.0 

func (mp *MultiPool) IsClosed() bool

IsClosed indicates whether the multi-pool is closed.

func (*MultiPool) Reboot added in v2.9.0 

func (mp *MultiPool) Reboot()

Reboot reboots a released multi-pool.

func (*MultiPool) ReleaseTimeout added in v2.9.0 

func (mp *MultiPool) ReleaseTimeout(timeout time.Duration) error

ReleaseTimeout closes the multi-pool with a timeout, it waits all pools to be closed before timing out.

func (*MultiPool) Running added in v2.9.0 

func (mp *MultiPool) Running() (n int)

Running returns the number of the currently running workers across all pools.

func (*MultiPool) RunningByIndex added in v2.9.0 

func (mp *MultiPool) RunningByIndex(idx int) (int, error)

RunningByIndex returns the number of the currently running workers in the specific pool.

func (*MultiPool) Submit added in v2.9.0 

func (mp *MultiPool) Submit(task func()) (err error)

Submit submits a task to a pool selected by the load-balancing strategy.

func (*MultiPool) Tune added in v2.9.0 

func (mp *MultiPool) Tune(size int)

Tune resizes each pool in multi-pool.

Note that this method doesn't resize the overall capacity of multi-pool.

func (*MultiPool) Waiting added in v2.9.0 

func (mp *MultiPool) Waiting() (n int)

Waiting returns the number of the currently waiting tasks across all pools.

func (*MultiPool) WaitingByIndex added in v2.9.0 

func (mp *MultiPool) WaitingByIndex(idx int) (int, error)

WaitingByIndex returns the number of the currently waiting tasks in the specific pool.

type MultiPoolWithFunc added in v2.9.0 

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

MultiPoolWithFunc consists of multiple pools, from which you will benefit the performance improvement on basis of the fine-grained locking that reduces the lock contention. MultiPoolWithFunc is a good fit for the scenario where you have a large number of tasks to submit, and you don't want the single pool to be the bottleneck.

Example 
atomic.StoreInt32(&sum, 0)
runTimes := 1000
wg.Add(runTimes)

mp, _ := ants.NewMultiPoolWithFunc(10, runTimes/10, incSum, ants.RoundRobin)
defer mp.ReleaseTimeout(time.Second) // nolint:errcheck

for i := 0; i < runTimes; i++ {
	_ = mp.Invoke(int32(i))
}
wg.Wait()

fmt.Printf("The result is %d\n", sum)

Output:

The result is 499500

func NewMultiPoolWithFunc added in v2.9.0 

func NewMultiPoolWithFunc(size, sizePerPool int, fn func(any), lbs LoadBalancingStrategy, options ...Option) (*MultiPoolWithFunc, error)

NewMultiPoolWithFunc instantiates a MultiPoolWithFunc with a size of the pool list and a size per pool, and the load-balancing strategy.

func (*MultiPoolWithFunc) Cap added in v2.9.0 

func (mp *MultiPoolWithFunc) Cap() (n int)

Cap returns the capacity of this multi-pool.

func (*MultiPoolWithFunc) Free added in v2.9.0 

func (mp *MultiPoolWithFunc) Free() (n int)

Free returns the number of available workers across all pools.

func (*MultiPoolWithFunc) FreeByIndex added in v2.9.0 

func (mp *MultiPoolWithFunc) FreeByIndex(idx int) (int, error)

FreeByIndex returns the number of available workers in the specific pool.

func (*MultiPoolWithFunc) Invoke added in v2.9.0 

func (mp *MultiPoolWithFunc) Invoke(args any) (err error)

Invoke submits a task to a pool selected by the load-balancing strategy.

func (*MultiPoolWithFunc) IsClosed added in v2.9.0 

func (mp *MultiPoolWithFunc) IsClosed() bool

IsClosed indicates whether the multi-pool is closed.

func (*MultiPoolWithFunc) Reboot added in v2.9.0 

func (mp *MultiPoolWithFunc) Reboot()

Reboot reboots a released multi-pool.

func (*MultiPoolWithFunc) ReleaseTimeout added in v2.9.0 

func (mp *MultiPoolWithFunc) ReleaseTimeout(timeout time.Duration) error

ReleaseTimeout closes the multi-pool with a timeout, it waits all pools to be closed before timing out.

func (*MultiPoolWithFunc) Running added in v2.9.0 

func (mp *MultiPoolWithFunc) Running() (n int)

Running returns the number of the currently running workers across all pools.

func (*MultiPoolWithFunc) RunningByIndex added in v2.9.0 

func (mp *MultiPoolWithFunc) RunningByIndex(idx int) (int, error)

RunningByIndex returns the number of the currently running workers in the specific pool.

func (*MultiPoolWithFunc) Tune added in v2.9.0 

func (mp *MultiPoolWithFunc) Tune(size int)

Tune resizes each pool in multi-pool.

Note that this method doesn't resize the overall capacity of multi-pool.

func (*MultiPoolWithFunc) Waiting added in v2.9.0 

func (mp *MultiPoolWithFunc) Waiting() (n int)

Waiting returns the number of the currently waiting tasks across all pools.

func (*MultiPoolWithFunc) WaitingByIndex added in v2.9.0 

func (mp *MultiPoolWithFunc) WaitingByIndex(idx int) (int, error)

WaitingByIndex returns the number of the currently waiting tasks in the specific pool.

type MultiPoolWithFuncGeneric added in v2.11.0 

type MultiPoolWithFuncGeneric[T any] struct {
	// contains filtered or unexported fields
}

MultiPoolWithFuncGeneric is the generic version of MultiPoolWithFunc.

Example 
atomic.StoreInt32(&sum, 0)
runTimes := 1000
wg.Add(runTimes)

mp, _ := ants.NewMultiPoolWithFuncGeneric(10, runTimes/10, incSumInt, ants.RoundRobin)
defer mp.ReleaseTimeout(time.Second) // nolint:errcheck

for i := 0; i < runTimes; i++ {
	_ = mp.Invoke(int32(i))
}
wg.Wait()

fmt.Printf("The result is %d\n", sum)

Output:

The result is 499500

func NewMultiPoolWithFuncGeneric added in v2.11.0 

func NewMultiPoolWithFuncGeneric[T any](size, sizePerPool int, fn func(T), lbs LoadBalancingStrategy, options ...Option) (*MultiPoolWithFuncGeneric[T], error)

NewMultiPoolWithFuncGeneric instantiates a MultiPoolWithFunc with a size of the pool list and a size per pool, and the load-balancing strategy.

func (*MultiPoolWithFuncGeneric[T]) Cap added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Cap() (n int)

Cap returns the capacity of this multi-pool.

func (*MultiPoolWithFuncGeneric[T]) Free added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Free() (n int)

Free returns the number of available workers across all pools.

func (*MultiPoolWithFuncGeneric[T]) FreeByIndex added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) FreeByIndex(idx int) (int, error)

FreeByIndex returns the number of available workers in the specific pool.

func (*MultiPoolWithFuncGeneric[T]) Invoke added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Invoke(args T) (err error)

Invoke submits a task to a pool selected by the load-balancing strategy.

func (*MultiPoolWithFuncGeneric[T]) IsClosed added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) IsClosed() bool

IsClosed indicates whether the multi-pool is closed.

func (*MultiPoolWithFuncGeneric[T]) Reboot added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Reboot()

Reboot reboots a released multi-pool.

func (*MultiPoolWithFuncGeneric[T]) ReleaseTimeout added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) ReleaseTimeout(timeout time.Duration) error

ReleaseTimeout closes the multi-pool with a timeout, it waits all pools to be closed before timing out.

func (*MultiPoolWithFuncGeneric[T]) Running added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Running() (n int)

Running returns the number of the currently running workers across all pools.

func (*MultiPoolWithFuncGeneric[T]) RunningByIndex added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) RunningByIndex(idx int) (int, error)

RunningByIndex returns the number of the currently running workers in the specific pool.

func (*MultiPoolWithFuncGeneric[T]) Tune added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Tune(size int)

Tune resizes each pool in multi-pool.

Note that this method doesn't resize the overall capacity of multi-pool.

func (*MultiPoolWithFuncGeneric[T]) Waiting added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) Waiting() (n int)

Waiting returns the number of the currently waiting tasks across all pools.

func (*MultiPoolWithFuncGeneric[T]) WaitingByIndex added in v2.11.0 

func (mp *MultiPoolWithFuncGeneric[T]) WaitingByIndex(idx int) (int, error)

WaitingByIndex returns the number of the currently waiting tasks in the specific pool.

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(any)) 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(any)

	// 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 is a goroutine pool that limits and recycles a mass of goroutines. The pool capacity can be fixed or unlimited.

Example 
ants.Reboot() // ensure the default pool is available

atomic.StoreInt32(&sum, 0)
runTimes := 1000
wg.Add(runTimes)
// Use the default pool.
for i := 0; i < runTimes; i++ {
	j := i
	_ = ants.Submit(func() {
		incSumInt(int32(j))
	})
}
wg.Wait()
fmt.Printf("The result is %d\n", sum)

atomic.StoreInt32(&sum, 0)
wg.Add(runTimes)
// Use the new pool.
pool, _ := ants.NewPool(10)
defer pool.Release()
for i := 0; i < runTimes; i++ {
	j := i
	_ = pool.Submit(func() {
		incSumInt(int32(j))
	})
}
wg.Wait()
fmt.Printf("The result is %d\n", sum)

Output:

The result is 499500
The result is 499500

func NewPool 

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

NewPool instantiates a Pool with customized options.

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 workers, -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, it does nothing if the pool is not closed. If you intend to reboot a closed pool, use ReleaseTimeout() instead of Release() to ensure that all workers are stopped and resource are released before rebooting, otherwise you may run into data race.

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 the 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 last 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 waiting to be executed.

type PoolWithFunc 

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

PoolWithFunc is like Pool but accepts a unified function for all goroutines to execute.

Example 
atomic.StoreInt32(&sum, 0)
runTimes := 1000
wg.Add(runTimes)

pool, _ := ants.NewPoolWithFunc(10, incSum)
defer pool.Release()

for i := 0; i < runTimes; i++ {
	_ = pool.Invoke(int32(i))
}
wg.Wait()

fmt.Printf("The result is %d\n", sum)

Output:

The result is 499500

func NewPoolWithFunc 

func NewPoolWithFunc(size int, pf func(any), options ...Option) (*PoolWithFunc, error)

NewPoolWithFunc instantiates a PoolWithFunc with customized options.

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 workers, -1 indicates this pool is unlimited.

func (*PoolWithFunc) Invoke 

func (p *PoolWithFunc) Invoke(arg any) error

Invoke passes arguments to the 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 last 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, it does nothing if the pool is not closed. If you intend to reboot a closed pool, use ReleaseTimeout() instead of Release() to ensure that all workers are stopped and resource are released before rebooting, otherwise you may run into data race.

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 waiting to be executed.

type PoolWithFuncGeneric added in v2.11.0 

type PoolWithFuncGeneric[T any] struct {
	// contains filtered or unexported fields
}

PoolWithFuncGeneric is the generic version of PoolWithFunc.

Example 
atomic.StoreInt32(&sum, 0)
runTimes := 1000
wg.Add(runTimes)

pool, _ := ants.NewPoolWithFuncGeneric(10, incSumInt)
defer pool.Release()

for i := 0; i < runTimes; i++ {
	_ = pool.Invoke(int32(i))
}
wg.Wait()

fmt.Printf("The result is %d\n", sum)

Output:

The result is 499500

func NewPoolWithFuncGeneric added in v2.11.0 

func NewPoolWithFuncGeneric[T any](size int, pf func(T), options ...Option) (*PoolWithFuncGeneric[T], error)

NewPoolWithFuncGeneric instantiates a PoolWithFuncGeneric[T] with customized options.

func (PoolWithFuncGeneric) Cap added in v2.11.0 

func (p PoolWithFuncGeneric) Cap() int

Cap returns the capacity of this pool.

func (PoolWithFuncGeneric) Free added in v2.11.0 

func (p PoolWithFuncGeneric) Free() int

Free returns the number of available workers, -1 indicates this pool is unlimited.

func (*PoolWithFuncGeneric[T]) Invoke added in v2.11.0 

func (p *PoolWithFuncGeneric[T]) Invoke(arg T) error

Invoke passes the argument to the pool to start a new task.

func (PoolWithFuncGeneric) IsClosed added in v2.11.0 

func (p PoolWithFuncGeneric) IsClosed() bool

IsClosed indicates whether the pool is closed.

func (PoolWithFuncGeneric) Reboot added in v2.11.0 

func (p PoolWithFuncGeneric) Reboot()

Reboot reboots a closed pool, it does nothing if the pool is not closed. If you intend to reboot a closed pool, use ReleaseTimeout() instead of Release() to ensure that all workers are stopped and resource are released before rebooting, otherwise you may run into data race.

func (PoolWithFuncGeneric) Release added in v2.11.0 

func (p PoolWithFuncGeneric) Release()

Release closes this pool and releases the worker queue.

func (PoolWithFuncGeneric) ReleaseTimeout added in v2.11.0 

func (p PoolWithFuncGeneric) ReleaseTimeout(timeout time.Duration) error

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

func (PoolWithFuncGeneric) Running added in v2.11.0 

func (p PoolWithFuncGeneric) Running() int

Running returns the number of workers currently running.

func (PoolWithFuncGeneric) Tune added in v2.11.0 

func (p PoolWithFuncGeneric) Tune(size int)

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

func (PoolWithFuncGeneric) Waiting added in v2.11.0 

func (p PoolWithFuncGeneric) Waiting() int

Waiting returns the number of tasks waiting to be executed.

Source Files

View all Source files

Directories

Path Synopsis
pkg
sync
Package sync provides some handy implementations for synchronization access.
 Package sync provides some handy implementations for synchronization access.

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.