base on 🐜🐜🐜 ants is the most powerful and reliable pooling solution for Go. <p align="center"> <img src="https://raw.githubusercontent.com/panjf2000/logos/master/ants/logo.png" /> <b>A goroutine pool for Go</b> <br/><br/> <a title="Build Status" target="_blank" href="https://github.com/panjf2000/ants/actions?query=workflow%3ATests"><img src="https://img.shields.io/github/actions/workflow/status/panjf2000/ants/test.yml?branch=master&style=flat-square&logo=github-actions" /></a> <a title="Codecov" target="_blank" href="https://codecov.io/gh/panjf2000/ants"><img src="https://img.shields.io/codecov/c/github/panjf2000/ants?style=flat-square&logo=codecov" /></a> <a title="Release" target="_blank" href="https://github.com/panjf2000/ants/releases"><img src="https://img.shields.io/github/v/release/panjf2000/ants.svg?color=161823&style=flat-square&logo=smartthings" /></a> <a title="Tag" target="_blank" href="https://github.com/panjf2000/ants/tags"><img src="https://img.shields.io/github/v/tag/panjf2000/ants?color=%23ff8936&logo=fitbit&style=flat-square" /></a> <br/> <a title="Go Report Card" target="_blank" href="https://goreportcard.com/report/github.com/panjf2000/ants"><img src="https://goreportcard.com/badge/github.com/panjf2000/ants?style=flat-square" /></a> <a title="Doc for ants" target="_blank" href="https://pkg.go.dev/github.com/panjf2000/ants/v2?tab=doc"><img src="https://img.shields.io/badge/go.dev-doc-007d9c?style=flat-square&logo=read-the-docs" /></a> <a title="Mentioned in Awesome Go" target="_blank" href="https://github.com/avelino/awesome-go#goroutines"><img src="https://awesome.re/mentioned-badge-flat.svg" /></a> </p> English | [中文](README_ZH.md) ## 📖 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 Golang - Nonblocking mechanism - Preallocated memory (ring buffer, optional) ## 💡 How `ants` works ### Flow Diagram <p align="center"> <img width="1011" alt="ants-flowchart-en" src="https://user-images.githubusercontent.com/7496278/66396509-7b42e700-ea0c-11e9-8612-b71a4b734683.png"> </p> ### Activity Diagrams     ## 🧰 How to install ### For `ants` v1 ``` powershell go get -u github.com/panjf2000/ants ``` ### For `ants` v2 (with GO111MODULE=on) ```powershell 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: ``` go 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 ```go // 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.Options`contains 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`method. ### 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: ``` go p, _ := ants.NewPool(10000) ``` ### Submit tasks Tasks can be submitted by calling `ants.Submit(func())` ```go ants.Submit(func(){}) ``` ### Tune pool capacity in runtime You can tune the capacity of `ants` pool in runtime with `Tune(int)`: ``` go 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. ```go // ants will pre-malloc the whole capacity of pool when you invoke this method p, _ := ants.NewPool(100000, ants.WithPreAlloc(true)) ``` ### Release Pool ```go pool.Release() ``` or ```go pool.ReleaseTimeout(time.Second * 3) ``` ### Reboot Pool ```go // 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](CONTRIBUTING.md) before opening a PR and thank you to all the developers who already made contributions to `ants`! <a href="https://github.com/panjf2000/ants/graphs/contributors"> <img src="https://contrib.rocks/image?repo=panjf2000/ants" /> </a> ## 📄 License The source code in `ants` is available under the [MIT License](/LICENSE). ## 📚 Relevant Articles - [Goroutine 并发调度模型深度解析之手撸一个高性能 goroutine 池](https://taohuawu.club/high-performance-implementation-of-goroutine-pool) - [Visually Understanding Worker Pool](https://medium.com/coinmonks/visually-understanding-worker-pool-48a83b7fc1f5) - [The Case For A Go Worker Pool](https://brandur.org/go-worker-pool) - [Go Concurrency - GoRoutines, Worker Pools and Throttling Made Simple](https://twin.sh/articles/39/go-concurrency-goroutines-worker-pools-and-throttling-made-simple) ## 🖥 Use cases ### business corporations Trusted by the following corporations/organizations. <table> <tbody> <tr> <td align="center" valign="middle"> <a href="https://www.tencent.com/"> <img src="https://res.strikefreedom.top/static_res/logos/tencent_logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.bytedance.com/en/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/ByteDance_Logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://tieba.baidu.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/baidu-tieba-logo.png" width="300" /> </a> </td> <td align="center" valign="middle"> <a href="https://weibo.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/weibo-logo.png" width="300" /> </a> </td> </tr> <tr> <td align="center" valign="middle"> <a href="https://www.tencentmusic.com/en-us/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/tencent-music-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.futuhk.com/en/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/futu-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.shopify.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/shopify-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.wechat.com/en/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/wechat-logo.png" width="250" /> </a> </td> </tr> <tr> <td align="center" valign="middle"> <a href="https://www.baidu.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/baidu-mobile-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.360.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/360-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.huaweicloud.com/intl/en-us/" target="_blank"> <img src="https://res-static.hc-cdn.cn/cloudbu-site/china/zh-cn/%E7%BB%84%E4%BB%B6%E9%AA%8C%E8%AF%81/pep-common-header/logo-en.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.matrixorigin.io/" target="_blank"> <img src="https://www.matrixorigin.io/_next/static/media/logo-light-en.42553c69.svg" width="250" /> </a> </td> </tr> <tr> <td align="center" valign="middle"> <a href="https://adguard-dns.io/" target="_blank"> <img src="https://cdn.adtidy.org/website/images/AdGuardDNS_black.svg" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://bk.tencent.com/" target="_blank"> <img src="https://static.apiseven.com/2022/11/14/6371adab14119.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.alibabacloud.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/aliyun-intl-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://www.zuoyebang.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/zuoyebang-logo.jpeg" width="300" /> </a> </td> </tr> <tr> <td align="center" valign="middle"> <a href="https://www.antgroup.com/en/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/ant-group-logo.png" width="250" /> </a> </td> <td align="center" valign="middle"> <a href="https://zilliz.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/zilliz-logo.png" width="250" /> </a> </td> </td> <td align="center" valign="middle"> <a href="https://amap.com/" target="_blank"> <img src="https://res.strikefreedom.top/static_res/logos/amap-logo.png" width="250" /> </a> </td> </tr> </tbody> </table> 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](https://github.com/panjf2000/gnet): A high-performance, lightweight, non-blocking, event-driven networking framework written in pure Go. - [milvus](https://github.com/milvus-io/milvus): An open-source vector database for scalable similarity search and AI applications. - [nps](https://github.com/ehang-io/nps): A lightweight, high-performance, powerful intranet penetration proxy server, with a powerful web management terminal. - [TDengine](https://github.com/taosdata/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](https://github.com/siyuan-note/siyuan): SiYuan is a local-first personal knowledge management system that supports complete offline use, as well as end-to-end encrypted synchronization. - [osmedeus](https://github.com/j3ssie/osmedeus): A Workflow Engine for Offensive Security. - [jitsu](https://github.com/jitsucom/jitsu/tree/master): 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](https://github.com/RH12503/triangula): Generate high-quality triangulated and polygonal art from images. - [teler](https://github.com/kitabisa/teler): Real-time HTTP Intrusion Detection. - [bsc](https://github.com/binance-chain/bsc): A Binance Smart Chain client based on the go-ethereum fork. - [jaeles](https://github.com/jaeles-project/jaeles): The Swiss Army knife for automated Web Application Testing. - [devlake](https://github.com/apache/incubator-devlake): The open-source dev data platform & dashboard for your DevOps tools. - [matrixone](https://github.com/matrixorigin/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](https://github.com/TencentBlueKing/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](https://github.com/TrueBlocks/trueblocks-core): TrueBlocks improves access to blockchain data for any EVM-compatible chain (particularly Ethereum mainnet) while remaining entirely local. - [openGemini](https://github.com/openGemini/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](https://github.com/AdguardTeam/AdGuardDNS): AdGuard DNS is an alternative solution for tracker blocking, privacy protection, and parental control. - [WatchAD2.0](https://github.com/Qihoo360/WatchAD2.0): WatchAD2.0 是 360 信息安全中心开发的一款针对域安全的日志分析与监控系统，它可以收集所有域控上的事件日志、网络流量，通过特征匹配、协议分析、历史行为、敏感操作和蜜罐账户等方式来检测各种已知与未知威胁，功能覆盖了大部分目前的常见内网域渗透手法。 - [vanus](https://github.com/vanus-labs/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](https://github.com/trpc-group/trpc-go): A pluggable, high-performance RPC framework written in Golang. - [motan-go](https://github.com/weibocom/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: - [Repositories that depend on ants/v2](https://github.com/panjf2000/ants/network/dependents?package_id=UGFja2FnZS0yMjY2ODgxMjg2) - [Repositories that depend on ants/v1](https://github.com/panjf2000/ants/network/dependents?package_id=UGFja2FnZS0yMjY0ODMzNjEw) 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. <a href="https://www.jetbrains.com/?from=ants" target="_blank"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg" alt="JetBrains logo."></a> ## 💰 Backers Support us with a monthly donation and help us continue our activities. <a href="https://opencollective.com/ants#backers" target="_blank"><img src="https://opencollective.com/ants/backers.svg"></a> ## 💎 Sponsors Become a bronze sponsor with a monthly donation of $10 and get your logo on our README on GitHub. <a href="https://opencollective.com/ants#sponsors" target="_blank"><img src="https://opencollective.com/ants/sponsors.svg"></a> ## ☕️ 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. <img src="https://raw.githubusercontent.com/panjf2000/illustrations/master/payments/WeChatPay.JPG" width="250" align="middle"/>&nbsp;&nbsp; <img src="https://raw.githubusercontent.com/panjf2000/illustrations/master/payments/AliPay.JPG" width="250" align="middle"/>&nbsp;&nbsp; <a href="https://www.paypal.me/R136a1X" target="_blank"><img src="https://raw.githubusercontent.com/panjf2000/illustrations/master/payments/PayPal.JPG" width="250" align="middle"/></a>&nbsp;&nbsp; ## 🔋 Sponsorship <p> <a href="https://www.digitalocean.com/"> <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" width="201px"> </a> </p> ", Assign "at most 3 tags" to the expected json: {"id":"5229","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"