Worker pools
A worker pool is a fixed number of goroutines reading from one channel of jobs. The number is chosen once, the jobs queue without creating a goroutine per item, and the pool ends when the jobs channel closes. It is the standard way to bound concurrency when the work talks to a database, a disk or a rate-limited API.
Three workers and a jobs channel
The workers range over jobs and each result goes to a second channel. The sender closes jobs when it is done, which ends every range; the main goroutine waits for the workers, closes results, and reads what is left. The order of the results is the order the workers happened to finish, so the program sorts before printing.
package main
import (
"fmt"
"sort"
"sync"
)
func worker(id int, jobs <-chan int, results chan<- int, wg *sync.WaitGroup) {
defer wg.Done()
for job := range jobs {
results <- job * job
}
}
func main() {
jobs := make(chan int, 5)
results := make(chan int, 5)
var wg sync.WaitGroup
for w := 1; w <= 3; w++ {
wg.Add(1)
go worker(w, jobs, results, &wg)
}
for i := 1; i <= 5; i++ {
jobs <- i
}
close(jobs)
wg.Wait()
close(results)
var squares []int
for r := range results {
squares = append(squares, r)
}
sort.Ints(squares)
fmt.Println("squares:", squares)
}
go build -o app main.go && ./app
squares: [1 4 9 16 25]
The worker parameter id is unused here, and Go allows an unused parameter, unlike an unused local variable. The channel sizes are the smallest that let the five sends finish before the workers start; a larger buffer is a decision about memory, not correctness.
A pool that stops on cancellation
A pool in a server must also stop when nobody wants the answer. Each worker selects between the context and the next job, and returns when either says stop. The ok from the receive ends the worker when the jobs channel is closed, and a third goroutine closes the results channel after the workers are done, which is the shape that lets the consumer range over the results.
package main
import (
"context"
"fmt"
"sync"
)
func worker(ctx context.Context, jobs <-chan int, done chan<- int) {
for {
select {
case <-ctx.Done():
return
case job, ok := <-jobs:
if !ok {
return
}
done <- job * 2
}
}
}
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
jobs := make(chan int)
done := make(chan int)
var wg sync.WaitGroup
for i := 1; i <= 2; i++ {
wg.Add(1)
go func() {
defer wg.Done()
worker(ctx, jobs, done)
}()
}
go func() {
for i := 1; i <= 4; i++ {
jobs <- i
}
close(jobs)
}()
go func() {
wg.Wait()
close(done)
}()
total := 0
for v := range done {
total += v
}
fmt.Println("total:", total)
}
go build -o app main.go && ./app
total: 20
The total is the sum of twice the four jobs, and the number of workers does not change it. The context in this program is cancelled by the deferred call only at the end, so this run finished normally; a request that times out cancels it earlier and the workers return without draining the queue, which is the behaviour a server wants.
A semaphore instead of a pool
Not every job needs a permanent worker. When the goroutines are created for one task each and only the number running at once must be bounded, a buffered channel used as a semaphore is simpler: a send takes a slot and a receive releases it, and the capacity is the limit. The four tasks below run two at a time.
package main
import (
"fmt"
"sync"
)
func main() {
sem := make(chan struct{}, 2)
var wg sync.WaitGroup
for i := 1; i <= 4; i++ {
wg.Add(1)
go func() {
defer wg.Done()
sem <- struct{}{}
defer func() { <-sem }()
fmt.Println("running", i)
}()
}
wg.Wait()
fmt.Println("all done")
}
go build -o app main.go && ./app
running 4
running 1
running 2
running 3
all done
The order changes between runs, and at most two running lines can be in flight at once. The deferred release is the important part: a panic in the task must not leak a slot, or the program deadlocks after two failures. A semaphore bounds concurrency; a pool reuses goroutines, which also saves their creation cost, and the two are often confused.
How many workers
For CPU-bound work the answer is runtime.NumCPU(), because more workers only add context switches. For network work the answer is the concurrency the far end allows: a database pool of ten, an API with a rate limit, a disk with a queue. The number belongs in configuration, not in a constant, and a pool that is too large is worse than a small one because it turns backpressure into timeouts.
The pool also needs an exit: close the jobs channel from the sender, wait for the workers, then close the results. A pool that reads from a channel nobody closes leaks its workers until the process ends, and a test that creates one per case accumulates them.
Exercises
- Change the pool to two workers and run it. What changes in the output, and what does not?
- Remove the close(jobs) and run the program. Which goroutines are still alive when main waits, and what does the runtime print?
- Set the semaphore capacity to four and then to one. How does the printed order change, and which limit would you choose for a pool of HTTP requests?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What ends a worker that ranges over a jobs channel?
Answer
The close of the channel
The sender closes it when there are no more jobs.
-
Who should close the results channel?
Answer
A goroutine that waits for the workers
The close must happen after the last result.
-
Why sort the results before printing?
Answer
The workers finish in no fixed order
The result channel keeps the finish order, not the job order.
-
What does a worker do on ctx.Done()?
Answer
Returns without draining the queue
A cancelled request does not need the rest of the work.
-
What does a buffered channel used as a semaphore do?
Answer
Limits how many goroutines hold a slot at once
Its capacity is the limit.
-
Why is the semaphore release deferred?
Answer
A panic must not leak a slot
A leaked slot deadlocks after enough failures.
-
How many workers for CPU-bound work?
Answer
About the number of CPUs
More workers only add context switches.
-
What limits the workers for network work?
Answer
What the far end or the connection pool allows
A database pool or a rate limit is the real bound.
-
What happens when a pool reads from a channel nobody closes?
Answer
The workers stay blocked and leak until the process ends
A range waits for a close that never comes.
-
What is the difference between a pool and a semaphore?
Answer
A pool reuses goroutines; a semaphore only bounds how many run
Both bound concurrency, at different costs.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev