{"id":32522096,"url":"https://github.com/gregorykogan/worker-pool","last_synced_at":"2025-10-28T06:52:10.858Z","repository":{"id":314160665,"uuid":"1054212715","full_name":"GregoryKogan/worker-pool","owner":"GregoryKogan","description":"An idiomatic Go worker pool with zero-allocation submissions, backpressure, and graceful shutdown.","archived":false,"fork":false,"pushed_at":"2025-09-10T23:47:25.000Z","size":363,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-11T00:23:12.104Z","etag":null,"topics":["concurrency","go","golang","goroutines","high-performance","library","parallelism","performance","production-ready","thread-pool","utility","worker-pool","zero-allocation"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/GregoryKogan/worker-pool","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GregoryKogan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-10T14:17:56.000Z","updated_at":"2025-09-10T23:36:40.000Z","dependencies_parsed_at":"2025-09-11T00:24:31.725Z","dependency_job_id":"04dc19af-07cc-4dd4-a5a2-31fe1733afa2","html_url":"https://github.com/GregoryKogan/worker-pool","commit_stats":null,"previous_names":["gregorykogan/worker-pool"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/GregoryKogan/worker-pool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fworker-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fworker-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fworker-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fworker-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GregoryKogan","download_url":"https://codeload.github.com/GregoryKogan/worker-pool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fworker-pool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281397296,"owners_count":26493908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concurrency","go","golang","goroutines","high-performance","library","parallelism","performance","production-ready","thread-pool","utility","worker-pool","zero-allocation"],"created_at":"2025-10-28T06:52:08.342Z","updated_at":"2025-10-28T06:52:10.850Z","avatar_url":"https://github.com/GregoryKogan.png","language":"Go","readme":"# High-Performance, Zero-Allocation Go Worker Pool\n\n[![Go CI](https://github.com/GregoryKogan/worker-pool/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/GregoryKogan/worker-pool/actions/workflows/go.yml)\n![Coverage](https://img.shields.io/badge/Coverage-100.0%25-brightgreen)\n[![Go Report Card](https://goreportcard.com/badge/github.com/GregoryKogan/worker-pool)](https://goreportcard.com/report/github.com/GregoryKogan/worker-pool)\n[![Go Reference](https://pkg.go.dev/badge/github.com/GregoryKogan/worker-pool.svg)](https://pkg.go.dev/github.com/GregoryKogan/worker-pool)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n---\n\nA robust, idiomatic, and production-ready worker pool for Go that provides fine-grained control over concurrency with a focus on high performance and zero-allocation submissions.\n\nManaging a large number of concurrent tasks efficiently can be complex. Spawning an unbounded number of goroutines can lead to resource exhaustion and performance degradation due to scheduler overhead. This worker pool provides a simple, robust, and extremely fast way to control concurrency, process task queues, and manage graceful shutdowns, all while avoiding common pitfalls like deadlocks and race conditions.\n\n## Features\n\n- **Zero-Allocation `Submit`:** The hot path for submitting tasks is allocation-free, minimizing GC pressure in high-throughput applications.\n- **Automatic Backpressure:** The pool naturally applies backpressure when all workers are saturated, preventing unbounded queue growth and system overload.\n- **Graceful vs. Abrupt Shutdown:** Choose between two shutdown strategies: `StopWait()` to finish all queued tasks, or `Stop()` to terminate quickly, completing only in-flight tasks.\n- **Concurrency Safe:** Designed from the ground up to be safe for concurrent use and rigorously tested with the Go race detector.\n- **Panic Recovery:** Each worker is equipped with a panic recovery mechanism. If a submitted task panics, the pool logs the error and stack trace, then continues processing other tasks. This ensures the entire application remains stable and does not crash due to faulty user code.\n- **100% Test Coverage:** Every line of code is covered by deterministic unit and integration tests, ensuring reliability.\n\n## Performance Highlights\n\nThis library is built for speed. Benchmarks are conducted on an **Apple M1 Pro** with **8 performance cores**. The results demonstrate superior performance compared to naive goroutine spawning and showcase excellent scaling characteristics.\n\n### CPU-Bound Scaling\n\nFor CPU-bound tasks, the pool exhibits near-perfect linear scaling up to the number of available CPU cores, after which performance correctly plateaus. This demonstrates efficient core utilization without the overhead of excessive context switching.\n\n![CPU-Bound Task Scaling](results/plots/cpu_scaling.png)\n\n### I/O-Bound Scaling\n\nFor I/O-bound tasks (e.g., network requests, disk I/O), the pool demonstrates massive throughput gains as the number of workers increases. This is ideal for managing a large number of concurrent, non-blocking operations.\n\n![I/O-Bound Task Scaling](results/plots/io_scaling.png)\n\n### Submission Overhead vs. `go func()`\n\nThe primary goal of a worker pool is to amortize the cost of goroutine management. For high-throughput, short-lived tasks, the pool's submission overhead is significantly lower than the native `go func()` approach, thanks to its zero-allocation design.\n\n![Overhead Comparison](results/plots/overhead_comparison.png)\n\n## Installation\n\n```sh\ngo get github.com/GregoryKogan/worker-pool\n```\n\n## Usage\n\n### Quick Start\n\nHere is a simple example of creating a pool, submitting work, and shutting it down gracefully.\n\n```go\npackage main\n\nimport (\n \"fmt\"\n \"runtime\"\n \"sync/atomic\"\n \"time\"\n\n \"github.com/\u003cYOUR_USERNAME\u003e/\u003cYOUR_REPOSITORY\u003e\"\n)\n\nfunc main() {\n // Create a pool with a number of workers equal to the number of CPUs.\n pool := worker_pool.NewWorkerPool(runtime.NumCPU())\n\n var tasksCompleted atomic.Int64\n numTasks := 100\n\n // Submit 100 tasks to the pool.\n for i := 0; i \u003c numTasks; i++ {\n  taskID := i // Capture the loop variable\n  pool.Submit(func() {\n   fmt.Printf(\"Processing task %d...\\n\", taskID)\n   time.Sleep(10 * time.Millisecond)\n   tasksCompleted.Add(1)\n  })\n }\n\n fmt.Println(\"All tasks submitted. Waiting for completion...\")\n\n // Stop the pool and wait for all queued tasks to complete.\n pool.StopWait()\n\n fmt.Printf(\"All %d tasks have been completed.\\n\", tasksCompleted.Load())\n}\n```\n\n### API Overview\n\n- **`NewWorkerPool(numberOfWorkers int) *WorkerPool`**  \n    Creates and starts a new worker pool with the specified number of workers. Panics if `numberOfWorkers \u003c 1`.\n\n- **`Submit(task func())`**  \n    Adds a task to the pool for asynchronous execution. This is a non-blocking, zero-allocation call.\n\n- **`SubmitWait(task func())`**  \n    Adds a task to the pool and blocks until that specific task is completed.\n\n### Graceful Shutdown\n\nThe library provides two distinct shutdown methods to handle different application needs.\n\n- **`Stop()`**  \n    Initiates an **abrupt shutdown**. It signals all workers to stop after they finish their *currently executing* task. Any tasks waiting in the queue are discarded. This is useful for quick teardowns where pending work can be ignored.\n\n- **`StopWait()`**  \n    Initiates a **graceful shutdown**. The pool first stops accepting new tasks and then waits for all existing tasks—both those currently running and those waiting in the queue—to be completed before stopping the workers. This is the most common method for ensuring no work is lost.\n\n## Development \u0026 Benchmarking\n\nThis project is fully tested and benchmarked. You can run these commands yourself.\n\n**1. Run Tests:**  \nThe test suite is designed to be run with the race detector to ensure concurrency safety.\n\n```sh\ngo test -v -race ./...\n```\n\n**2. Generate Benchmark Data:**  \nTo reproduce the performance benchmarks, run the following command. The `-json` flag is required for the visualization script.\n\n```sh\n# Ensure the output directory exists\nmkdir -p results/benchmarks\n\n# Run benchmarks and save the machine-readable output\ngo test -bench=. -benchmem -benchtime=3s -json \u003e results/benchmarks/latest.json\n```\n\n**3. Visualize Benchmark Results:**  \nThe `scripts/` directory contains a Python script to generate the performance plots.\n\n```sh\n# (One-time setup) Create and activate a virtual environment\npython3 -m venv scripts/.venv\nsource scripts/.venv/bin/activate\npip install -r scripts/requirements.txt\n\n# Generate plots from the latest benchmark data\npython3 scripts/plot_benchmarks.py --input results/benchmarks/latest.json\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to open an issue to discuss a feature or bug, or submit a pull request with your changes.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregorykogan%2Fworker-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregorykogan%2Fworker-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregorykogan%2Fworker-pool/lists"}