ants

A goroutine pool for Go

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 Go - Nonblocking mechanism - Preallocated memory (ring buffer, optional) ## 💡 How `ants` works ### Flow Diagram

### 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 Check out [the examples](https://pkg.go.dev/github.com/panjf2000/ants/v2#pkg-examples) for basic usage. ### Functional options for pool `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`/`NewPoolWithFuncGeneric` method. Check out [ants.Options](https://pkg.go.dev/github.com/panjf2000/ants/v2#Options) and [ants.Option](https://pkg.go.dev/github.com/panjf2000/ants/v2#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: ``` go p, _ := ants.NewPool(10000) ``` ### Submit tasks Tasks can be submitted by calling `ants.Submit` ```go ants.Submit(func(){}) ``` ### Tune pool capacity at runtime You can tune the capacity of `ants` pool at runtime with `ants.Tune`: ``` 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 calling ants.NewPool. 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 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](CONTRIBUTING.md) 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](/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 & open-source organizations 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](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. - [BillionMail](https://github.com/aaPanel/BillionMail): A future open-source Mail server, Email marketing platform designed to help businesses and individuals manage their email campaigns with ease. - [WeKnora](https://github.com/Tencent/WeKnora): An LLM-powered framework designed for deep document understanding and semantic retrieval, especially for handling complex, heterogeneous documents. - [coze-loop](https://github.com/coze-dev/coze-loop): A developer-oriented, platform-level solution focused on the development and operation of AI agents. - [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