When to Use a Pool — Junior Level¶

Table of Contents¶

1. Introduction
2. Prerequisites
3. Glossary
4. Core Concepts
5. Real-World Analogies
6. Mental Models
7. The Simple Decision Tree
8. Code Examples
9. Side-by-Side Comparison
10. When Raw Goroutines Are Fine
11. When You Definitely Need Something
12. Coding Patterns
13. Clean Code
14. Error Handling
15. Performance Tips
16. Best Practices
17. Edge Cases & Pitfalls
18. Common Mistakes
19. Common Misconceptions
20. Tricky Points
21. Test
22. Tricky Questions
23. Cheat Sheet
24. Self-Assessment Checklist
25. Summary
26. What You Can Build
27. Further Reading
28. Related Topics
29. Diagrams & Visual Aids

Introduction¶

Focus: "I have learned about goroutines and channels. I have heard about pools. When do I actually need one, and when am I just adding code for no reason?"

You have arrived at a question every Go programmer hits within their first few months of working with concurrency. You write a small program that spawns 10 goroutines and it works. You write one that spawns 10,000 and it still works. Someone tells you about a library called ants that pools goroutines and you wonder: should you use it everywhere? Should you use it sometimes? Should you use it at all?

The short answer is that most of the time you do not need a third-party pool. The Go runtime is very good at scheduling goroutines, and the standard library — specifically golang.org/x/sync/errgroup — already gives you everything you need for the vast majority of "limit concurrent work" cases. Third-party pools shine in specific situations: when you are creating goroutines at extreme rates (hundreds of thousands per second), when you need worker reuse for warm state, when you need features that errgroup does not provide (metrics, dynamic resizing, non-blocking submit). For typical web servers, batch processors, and CLI tools, you almost never need them.

The trap is that pools look like a best practice — they look like the "professional" choice — when in fact they often add complexity, hide bugs, and slow things down. This document teaches you to recognise the small number of cases where a pool is the right tool, and the much larger number of cases where it is not.

After reading this file you will:

• Understand why "raw goroutine" is often the right answer
• Be able to draw a decision tree from "I have a parallel workload" to one of four answers: raw goroutines, errgroup, semaphore, or a third-party pool
• Recognise the three problems pools actually solve
• Write equivalent code in three styles — raw goroutines, errgroup, and an ants pool — and tell which is appropriate
• Know how to bound concurrency in standard-library Go with one line
• Avoid the "I added a pool because pools are good" anti-pattern
• Read code that uses pools and assess whether the pool was necessary

You do not need to know about the internals of ants, the locking strategies in tunny, or the allocation patterns of workerpool yet. Those come at the middle and senior levels. This file is about the question that comes first: do I even need a pool?

Prerequisites¶

• Required: You have written goroutines with the go keyword and waited for them with sync.WaitGroup. Comfortable with go f() and wg.Add(1); defer wg.Done().
• Required: You have used channels for at least basic producer/consumer coordination.
• Required: You have a Go installation 1.18 or newer (1.21+ recommended). golang.org/x/sync should be on your GOPATH or in your module.
• Helpful: You have read the previous topics in this concurrency track — at least 01-goroutines, 02-channels, and the earlier files in 17-goroutine-pools-3rd-party.
• Helpful: You have at least seen the words "OOM kill" in a production context. If not, "OOM" is when the kernel kills your process for using too much memory.
• Helpful: You have written or read code that calls an external API in parallel — a fan-out over a list of URLs is the canonical example.

If you can write a program that fetches 5 URLs in parallel and waits for all of them, you are ready.

Glossary¶

Core Concepts¶

What problem does a pool actually solve?¶

To know whether you need a pool, you must know what a pool is for. A pool solves exactly three problems, in order of frequency:

1. Bounded concurrency. You have N tasks (or an unbounded stream of them) and you want at most K to run at the same time. K is usually chosen for one of three reasons: a downstream rate limit (an API that allows 50 in-flight requests), a memory budget (each task uses 200 MB of RAM and you have 8 GB), or a CPU bound (each task is CPU-heavy and you have 8 cores). This is the problem pools solve. It is also the problem that errgroup.SetLimit solves with one line of standard-library code.

2. Worker reuse for warm state. Some tasks need to set up expensive state — a compiled regex, a connection to a service, a buffer — and you want that state to live as long as the worker, not as long as the task. Reusing workers lets you amortise the setup cost across many tasks. Most workloads do not have this property; the ones that do are usually obvious (each "task" must hold open a connection to a specific shard, for example).

3. Spawn-rate amortisation. Goroutines are cheap to exist, but they are not free to create. Creation costs about 1–2 microseconds and a small amount of heap. If you are spawning hundreds of thousands of goroutines per second, that cost adds up — both in CPU and in heap pressure for the garbage collector. Pools amortise this by spawning workers once and reusing them. This problem is rare. You need a workload like "handle 200K WebSocket messages/sec, each requiring a small CPU burst" before it shows up.

If your workload does not have any of these three problems, you do not need a pool. You may still benefit from errgroup for ergonomics, or from a chan and a few workers for shape, but you do not need a third-party library.

The three answers — and the fourth¶

Almost every Go concurrency design decision lands on one of four answers:

• Raw goroutines + WaitGroup. Use this when concurrency is naturally bounded by the problem (you have 5 things to do; you do 5 of them; you wait for all 5).
• errgroup.Group with SetLimit(K). Use this when you have many tasks and want to limit how many run at once, with error propagation and context cancellation. This is the standard answer for "I have 10,000 URLs to fetch, at most 50 at a time."
• semaphore.Weighted. Use this when tasks have unequal "weight" — some take 1 slot, others take 3 — or when you want the semaphore to live across functions and goroutines as a shared resource.
• Third-party pool (ants, tunny, workerpool). Use this when one of the three pool-only problems above applies, or when a feature you specifically need (dynamic resize, metrics, panic recovery, non-blocking submit) is not in the standard library.

That fourth answer is the focus of the rest of this subsection. The point of the junior file is to convince you that the first three answers cover 90%+ of cases.

Why goroutines are not free, but cheap enough¶

A common misconception is that "goroutines are cheap, so I should always spawn more." The reality is more nuanced:

• A goroutine starts with about 2 KB of stack. Memory is fine even at 100K goroutines (~200 MB).
• Goroutine creation costs about 1 μs. At 1M goroutines/sec, that's 1 CPU-core's worth of overhead.
• The scheduler does work proportional to runnable goroutines, not total goroutines. 10,000 sleeping goroutines cost nothing. 10,000 running goroutines all hammering the CPU cost a lot.
• Goroutines that perform syscalls (file I/O, network) park the OS thread. If many do this at once, the runtime spawns more OS threads — and threads cost 1–8 MB each.

The practical upshot for juniors: do not pool prematurely. If your service handles 100 RPS and each request spawns 5 goroutines, you have 500 active goroutines at peak. That is not a concurrency problem. Adding a pool will make the code more complex with zero measurable benefit.

What "bounded" actually means¶

When people say "we need bounded concurrency," they usually mean one of:

• "At most K of these can run at the same time." (the literal meaning)
• "We must not exceed K total goroutines in the program." (rare; usually wrong)
• "Slow down the producer when the consumer is backed up." (backpressure, usually solved by a bounded channel)
• "Don't OOM under load." (a memory budget, usually solved by limiting in-flight work)

Notice that "at most K at the same time" is not the same as "at most K total goroutines." You can have 10,000 goroutines in a program where only 50 are runnable at any one time and the rest are blocked on channels — and that is fine. The question is always "how many are running (or holding the resource we care about)?"

Real-World Analogies¶

The coffee shop¶

Picture a coffee shop. Customers arrive (tasks). The barista (worker) takes one order at a time and makes the drink. With one barista and a steady arrival rate, life is fine. When 20 customers walk in at once, a line forms. The barista keeps making drinks at the same rate, but customers wait. The system is back-pressured naturally.

Now imagine the manager says "every new customer should be served by a new barista that we hire on the spot." For one customer that works. For 20 it works barely. For 200 the shop is full of baristas bumping into each other, the coffee runs out, and the espresso machine catches fire.

• One barista forever = single-threaded; too slow for bursts.
• Hire-a-barista-per-customer = raw goroutines; fine until the burst is huge.
• Five baristas at fixed positions = a pool with K=5; bursts queue, throughput is bounded by 5.

Most of the time, your "shop" is not big enough to need pre-hired baristas. Five customers arrive, you spawn five goroutines, they all finish, life is good. The pool becomes necessary when the burst is large and the throughput limit matters (your "baristas" downstream API has a rate limit, or each "drink" eats memory).

The toll booth¶

A four-lane highway approaches a toll plaza. There are eight booths. At low traffic, cars pass through with no wait. At rush hour, a queue forms behind each booth — but only eight cars are paying at any moment. The booths are workers. The queue is the bounded buffer. The cars are tasks. Cars do not get to spawn new booths on demand.

A goroutine pool is the toll plaza. A raw goroutine fan-out is "every car drives off the road and pays a personal toll collector." The latter is faster when there are five cars; it is catastrophic when there are 5000.

The library returns desk¶

Books are returned to a library. The desk worker scans each one and shelves it. Books pile up (tasks queue), the worker scans them in order (FIFO), the system stays healthy. If you double the scanning rate by hiring a second worker, throughput doubles. Beyond a certain number of workers, the back-room shelving (downstream service) is the bottleneck and more workers add nothing.

This is the lesson of pool sizing: throughput is bounded by the slowest stage. Increasing the pool beyond the bottleneck just wastes goroutines.

The kitchen line¶

A restaurant kitchen has stations: chopping, sauteing, plating. Each station is staffed by a fixed number of cooks. Orders flow through the stations. The kitchen is a pipeline of pools, each sized for its station's throughput. You would not staff the chopping station with 50 cooks because the saute station only has 5. The pipeline is rate-limited by the smallest stage.

Most Go concurrency designs are similar — a chain of stages, each parallelised, each potentially needing a different K. Pools (or errgroups) give you per-stage control.

The roller coaster line¶

People queue, the train holds 24 riders, the train cycles every 90 seconds. Adding people to the queue does not increase throughput; the train is the rate limit. The queue is the bounded buffer in front of the worker pool. If the queue is uncapped, the wait becomes infinite; the park staff cuts off entry (drops tasks) at some queue length. This is the "non-blocking submit returns ErrPoolFull" pattern in ants.

Mental Models¶

The "do I need this?" funnel¶

Imagine a funnel with four exits. You feed your workload in at the top. It falls past four questions:

1. Is my workload bounded by the problem? (You have a fixed-size slice of inputs.) → If yes, raw goroutines + WaitGroup.
2. Are my tasks the same shape, with errors I care about and a context to cancel? → If yes, errgroup with SetLimit.
3. Do my tasks have unequal weight (some big, some small)? → If yes, semaphore.Weighted.
4. Do I need worker reuse, spawn-rate amortisation, or a feature like resize/metrics? → If yes, a third-party pool.

Most workloads stop at exit 1 or 2. If you fall through to exit 4, you are in the minority — and that is OK; it is what this subsection is for. The mistake to avoid is going straight to exit 4 because it sounds professional.

The "what is being limited" model¶

When you say "I want bounded concurrency," ask yourself: what scarce thing am I rationing? The answer is almost never "goroutines themselves." It is usually:

• HTTP requests to a downstream service (limit = its concurrency budget)
• Database connections (limit = pool size)
• File descriptors (limit = ulimit/2)
• CPU cores for CPU-bound work (limit = GOMAXPROCS)
• Memory for fat tasks (limit = budget / per-task footprint)

Whatever the limit is, the K in your pool or semaphore is determined by it. Pools do not invent a limit; they enforce one you already know.

The cost-benefit model¶

Every concurrency primitive has a cost — code, dependencies, mental load — and a benefit — fewer bugs, more throughput, better tail latency. Raw goroutines have the lowest cost and the highest risk. Third-party pools have the highest cost and (when needed) the highest benefit. The whole point of this subsection is to put you in the right place on the cost-benefit curve for your workload.

A useful rule: do not add a tool until you can measure the benefit. "I'll add ants because it might help" is bad reasoning. "We measured 12 GB heap from goroutine creation under load and ants brought it to 400 MB" is good reasoning.

The "tail" model¶

When you make decisions about concurrency, think about the worst case, not the average. The average case is usually fine without a pool. The 99th-percentile burst is what kills you. A service that runs cleanly at 100 RPS average can collapse at 1000 RPS for 10 seconds during a deploy or an upstream retry storm. A pool's value shows up in the tail.

The "what if I do nothing" model¶

Before adding a pool, ask: what if I do nothing? Spawn a goroutine per task, no bound. Run the program for an hour. What goes wrong? If the answer is "nothing," you do not need a pool. If the answer is "we OOM at 11pm when the cron fires," you need a bound — possibly errgroup, possibly a pool. If the answer is "we are fine but I worry about it," you do not need a pool; you need a monitoring dashboard.

The Simple Decision Tree¶

Here is the tree, in text form. We will turn it into a flowchart later in the file.

Q1: How many tasks will run concurrently (peak)?
    - Single-digit (you know each one by name) → raw goroutines + WaitGroup. Done.
    - Tens to hundreds → answer Q2.
    - Thousands+ → answer Q2 and Q3.

Q2: Do tasks share an error channel, a context, or both?
    - Yes → use errgroup. Use SetLimit(K) to bound. Done.
    - No, tasks are fire-and-forget with no errors → answer Q3.

Q3: Do you need bounded concurrency? (Why?)
    - "To not OOM" → errgroup with SetLimit, or semaphore. Done.
    - "Downstream API rate limit" → errgroup with SetLimit. Done.
    - "CPU cores" → errgroup with SetLimit(runtime.NumCPU()). Done.
    - "Tasks have unequal weight" → semaphore.Weighted. Done.
    - "I expect millions of tasks per second" → third-party pool. Answer Q4.

Q4: Which third-party pool?
    - Tasks return values you want to receive synchronously → tunny.
    - Tasks are fire-and-forget at very high rate → ants.
    - Tasks need FIFO ordering with a simple API → workerpool.
    - I want metrics, dynamic resize, multiple queues → ants or pond.

Q5: Are you sure? Have you measured?
    - No → go back to errgroup.SetLimit and measure first.
    - Yes → use the third-party pool you chose.

Most paths exit before Q4. The point of writing the tree out is to make it concrete: each downward arrow has a reason. If you find yourself at Q4 without a measured reason, retreat to Q3.

The 90-second version¶

Even shorter:

• Default to errgroup.SetLimit(K).
• If errgroup is overkill (you have 5 things to do), use raw goroutines.
• If errgroup is under-powered (unequal task weight, dynamic resize, metrics needed), use a third-party pool — and have a measurable reason.

This three-line rule covers most production code you will ever write.

Code Examples¶

The best way to feel the decision is to write the same problem three ways. Our problem: fetch 100 URLs in parallel, at most 10 at a time, collect the status codes, fail fast on the first error.

Example 1: Raw goroutines (incorrect — no bound)¶

This is the naive first attempt. It works for 10 URLs, fails for 10,000.

package main

import (
    "fmt"
    "net/http"
    "sync"
)

func main() {
    urls := []string{
        "https://example.com",
        "https://golang.org",
        // ... 98 more
    }

    var wg sync.WaitGroup
    statuses := make([]int, len(urls))

    for i, u := range urls {
        wg.Add(1)
        go func(i int, u string) {
            defer wg.Done()
            resp, err := http.Get(u)
            if err != nil {
                statuses[i] = -1
                return
            }
            defer resp.Body.Close()
            statuses[i] = resp.StatusCode
        }(i, u)
    }

    wg.Wait()
    for i, s := range statuses {
        fmt.Printf("%d %s -> %d\n", i, urls[i], s)
    }
}

What is wrong? No bound. For 100 URLs we open 100 HTTP connections at once. For 10,000 URLs we open 10,000 — and we hit EMFILE (too many open files) on the local side, hit per-host concurrency limits on the server side, and waste memory holding 10,000 in-flight responses. We also do not propagate errors; we silently turn failure into -1. We do not propagate cancellation.

This is the version a junior writes on day 1. It is fine for 5 inputs. It is wrong for 5000.

Example 2: Bounded with errgroup (correct, idiomatic)¶

The standard answer. One import, one SetLimit, error propagation, context cancellation.

package main

import (
    "context"
    "fmt"
    "net/http"
    "time"

    "golang.org/x/sync/errgroup"
)

func main() {
    urls := []string{
        "https://example.com",
        "https://golang.org",
        // ... 98 more
    }

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10) // at most 10 concurrent fetches

    statuses := make([]int, len(urls))

    for i, u := range urls {
        i, u := i, u // capture
        g.Go(func() error {
            req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
            if err != nil {
                return err
            }
            resp, err := http.DefaultClient.Do(req)
            if err != nil {
                return err
            }
            defer resp.Body.Close()
            statuses[i] = resp.StatusCode
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        fmt.Println("error:", err)
        return
    }

    for i, s := range statuses {
        fmt.Printf("%d %s -> %d\n", i, urls[i], s)
    }
}

What changed?

• errgroup.WithContext gives us a ctx that is cancelled the moment any goroutine returns an error.
• g.SetLimit(10) blocks g.Go(...) until fewer than 10 goroutines are in flight. The blocking is the bound; you cannot exceed it.
• The HTTP request is built with the cancellation-aware context, so when one fails, the others terminate early.
• g.Wait() returns the first error encountered.

This is the right answer for 95%+ of "fan out to N tasks, bounded" workloads. You almost never need more.

Example 3: Bounded with a third-party pool (overkill here)¶

The same workload, written with panjf2000/ants. This is what an over-eager junior writes after reading a blog post.

package main

import (
    "context"
    "fmt"
    "net/http"
    "sync"
    "time"

    "github.com/panjf2000/ants/v2"
)

func main() {
    urls := []string{
        "https://example.com",
        "https://golang.org",
        // ... 98 more
    }

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    statuses := make([]int, len(urls))
    var firstErr error
    var errMu sync.Mutex

    pool, err := ants.NewPool(10) // 10 workers
    if err != nil {
        panic(err)
    }
    defer pool.Release()

    var wg sync.WaitGroup
    for i, u := range urls {
        i, u := i, u
        wg.Add(1)
        _ = pool.Submit(func() {
            defer wg.Done()
            req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
            if err != nil {
                errMu.Lock()
                if firstErr == nil {
                    firstErr = err
                    cancel()
                }
                errMu.Unlock()
                return
            }
            resp, err := http.DefaultClient.Do(req)
            if err != nil {
                errMu.Lock()
                if firstErr == nil {
                    firstErr = err
                    cancel()
                }
                errMu.Unlock()
                return
            }
            defer resp.Body.Close()
            statuses[i] = resp.StatusCode
        })
    }

    wg.Wait()

    if firstErr != nil {
        fmt.Println("error:", firstErr)
        return
    }

    for i, s := range statuses {
        fmt.Printf("%d %s -> %d\n", i, urls[i], s)
    }
}

Look at the cost we just paid:

• We added a dependency (github.com/panjf2000/ants/v2).
• We had to reinvent error propagation with a mutex.
• We had to reinvent cancellation: when one fails, we cancel() manually.
• We still need a sync.WaitGroup because ants.Submit is fire-and-forget.

What did we gain?

• Worker reuse — but we run 100 tasks once and exit. Reuse is irrelevant.
• Spawn-rate amortisation — but we are not spawning at any rate worth amortising.
• A pool API — for a workload that fits a for loop.

For this workload, the third-party pool is worse than errgroup. It is more code, more dependency, less idiomatic, and gains nothing measurable. The right answer here is example 2.

This does not mean ants is bad. It means ants is the wrong tool for this job. The middle and senior files explore jobs where it is the right tool.

Example 4: When raw goroutines are right¶

To balance the picture: here is a case where Example 1's style is correct.

package main

import (
    "fmt"
    "sync"
)

func computeRow(row int) int {
    // pretend this is expensive
    total := 0
    for i := 0; i < 1000; i++ {
        total += row * i
    }
    return total
}

func main() {
    rows := []int{1, 2, 3, 4, 5, 6, 7, 8}
    results := make([]int, len(rows))

    var wg sync.WaitGroup
    for i, r := range rows {
        i, r := i, r
        wg.Add(1)
        go func() {
            defer wg.Done()
            results[i] = computeRow(r)
        }()
    }
    wg.Wait()
    fmt.Println(results)
}

8 tasks. 8 goroutines. No bound needed because the problem is bounded. No errors. No cancellation. No pool. This is correct. Adding errgroup here is fine but not necessary; adding a pool would be ridiculous.

Example 5: When a semaphore is right¶

Now imagine the tasks have unequal weight. Some are "small" (CPU-bound, 1 slot) and some are "big" (memory-bound, 3 slots). You have a fixed pool of 10 slots.

package main

import (
    "context"
    "fmt"
    "sync"

    "golang.org/x/sync/semaphore"
)

type Job struct {
    id     int
    weight int64
}

func main() {
    sem := semaphore.NewWeighted(10)
    ctx := context.Background()

    jobs := []Job{
        {1, 1}, {2, 3}, {3, 1}, {4, 5},
        {5, 1}, {6, 2}, {7, 1}, {8, 4},
    }

    var wg sync.WaitGroup
    for _, j := range jobs {
        j := j
        wg.Add(1)
        go func() {
            defer wg.Done()
            if err := sem.Acquire(ctx, j.weight); err != nil {
                fmt.Println("acquire err:", err)
                return
            }
            defer sem.Release(j.weight)
            fmt.Printf("running job %d (weight %d)\n", j.id, j.weight)
            // do work
        }()
    }
    wg.Wait()
}

A pool would force you to set every task to one slot. The semaphore lets a "weight 5" task hold half the budget while three "weight 1" tasks run beside it. That ergonomic is the reason semaphore.Weighted exists — and is the reason it is sometimes the right answer over errgroup.

Example 6: When a third-party pool is actually right¶

A scenario where ants earns its keep: a long-running service that receives millions of small CPU-bound tasks per second from many sources, and you want to recycle a fixed pool of warm workers.

package main

import (
    "fmt"
    "sync"
    "sync/atomic"
    "time"

    "github.com/panjf2000/ants/v2"
)

var processed atomic.Int64

func work() {
    // imagine some short CPU burst, e.g. hash a message
    for i := 0; i < 100; i++ {
        _ = i * i
    }
    processed.Add(1)
}

func main() {
    pool, err := ants.NewPool(1024)
    if err != nil {
        panic(err)
    }
    defer pool.Release()

    stop := make(chan struct{})
    var producers sync.WaitGroup
    for p := 0; p < 16; p++ {
        producers.Add(1)
        go func() {
            defer producers.Done()
            for {
                select {
                case <-stop:
                    return
                default:
                    _ = pool.Submit(work)
                }
            }
        }()
    }

    time.Sleep(5 * time.Second)
    close(stop)
    producers.Wait()

    // drain
    for pool.Running() > 0 {
        time.Sleep(10 * time.Millisecond)
    }

    fmt.Println("processed:", processed.Load())
    fmt.Println("workers:", pool.Cap())
}

Here the pool earns its keep: the production rate (millions per second) means raw go work() would burn CPU on creation alone, and errgroup.SetLimit would do similar gating but with extra coordination cost per call. The warm worker model wins. But notice: even this is borderline. Many services that look like this are not actually pushing millions/sec; they push thousands/sec and would be fine without ants. Measure first.

Side-by-Side Comparison¶

Below is a one-page comparison of the four answers, for the same "fetch 50 URLs at most 5 at a time" workload.

Raw goroutines + manual bound (token channel)¶

sem := make(chan struct{}, 5)
var wg sync.WaitGroup
for _, u := range urls {
    u := u
    wg.Add(1)
    sem <- struct{}{}
    go func() {
        defer wg.Done()
        defer func() { <-sem }()
        fetch(u)
    }()
}
wg.Wait()

• Lines: 11
• Dependencies: none
• Error handling: manual
• Cancellation: manual
• When to use: quick scripts, low complexity

errgroup with SetLimit¶

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(5)
for _, u := range urls {
    u := u
    g.Go(func() error { return fetch(ctx, u) })
}
return g.Wait()

• Lines: 6
• Dependencies: one (golang.org/x/sync/errgroup, semi-standard)
• Error handling: automatic (first error wins)
• Cancellation: automatic via shared ctx
• When to use: default answer for fan-out with bound

semaphore.Weighted¶

sem := semaphore.NewWeighted(5)
var wg sync.WaitGroup
for _, u := range urls {
    u := u
    wg.Add(1)
    go func() {
        defer wg.Done()
        if err := sem.Acquire(ctx, 1); err != nil { return }
        defer sem.Release(1)
        fetch(ctx, u)
    }()
}
wg.Wait()

• Lines: 11
• Dependencies: one (golang.org/x/sync/semaphore)
• Error handling: manual
• Cancellation: via ctx in Acquire
• When to use: unequal task weights, semaphore shared across functions

Third-party pool (ants)¶

pool, _ := ants.NewPool(5)
defer pool.Release()
var wg sync.WaitGroup
for _, u := range urls {
    u := u
    wg.Add(1)
    _ = pool.Submit(func() { defer wg.Done(); fetch(ctx, u) })
}
wg.Wait()

• Lines: 8
• Dependencies: one (github.com/panjf2000/ants/v2)
• Error handling: manual
• Cancellation: manual
• When to use: when you have a measured reason

The point of the side-by-side: errgroup is the fewest lines, fewest manual responsibilities, most idiomatic of the four. That is why it should be your default.

When Raw Goroutines Are Fine¶

The bias of this whole subsection is "do not pool prematurely." Here are the cases where you definitely should not pool — and should use raw go f() and be done.

Case A: Bounded by the problem¶

You have a fixed slice of inputs, you spawn one goroutine per input, you wait, you continue. Example: "fetch 5 sub-resources for this request and combine the results." WaitGroup plus 5 go calls. Adding errgroup is fine but optional. Adding a pool is wrong.

Case B: A single background task¶

You start one goroutine at program startup that watches a config file or refreshes a cache every minute. There is no second goroutine to coordinate with. There is no pool. There is no fan-out. There is go watchConfig(). That's it.

Case C: Short-lived "do-this-while" goroutines¶

You write a function that should report progress to a log every second while it works. You spawn one goroutine that loops on a ticker and stops when the function returns. Pool? No. go func() { for { ... } }() and a done channel. Done.

Case D: An event loop with one consumer goroutine per producer¶

Every connection in a server is "one goroutine for read, one for write." There is no pool because each goroutine is bound to one connection. Net/http already does this for you. The number of goroutines tracks the number of clients. The OS limits the number of clients via fd limits. You do not need a pool on top.

Case E: Tests and benchmarks¶

In a test, you often spawn a goroutine to drive the system under test, with no concern for production-grade boundedness. Raw goroutines are fine. A pool here is over-engineering.

Case F: CLI tools that exit immediately¶

A one-shot tool like "rsync this directory tree in parallel" spawns hundreds of goroutines, waits, exits. No long-lived service means no long-lived pool. You may still want a bound (use errgroup.SetLimit), but you do not need worker reuse.

If your case fits any of A–F, do not reach for a pool.

When You Definitely Need Something¶

Conversely, here are the situations where you absolutely must do something more than go f().

Trigger 1: Workload size is unbounded or huge¶

Anytime the number of tasks is "input-driven, possibly large" — millions of rows, hundreds of thousands of URLs, an unbounded stream from Kafka — you need a bound. errgroup.SetLimit first; pool only if you have measured a need.

Trigger 2: Downstream service has a concurrency limit¶

You are calling an API documented as "max 50 concurrent requests per API key." Without a bound you will exceed it and start getting 429s. With a bound of 50 (SetLimit(50)) you stay under. Easy choice; errgroup covers it.

Trigger 3: Memory budget¶

Each task uses 200 MB of working set. You have 16 GB. You can run at most ~70 in parallel before OOM. errgroup.SetLimit(50) keeps you safe. (You might also need to limit allocation rate, but bounding concurrency is step 1.)

Trigger 4: CPU-bound work¶

You have a CPU-bound job (image processing, hashing, compression). The CPU limit is runtime.NumCPU(). Adding more workers than cores hurts throughput because of scheduler contention. errgroup.SetLimit(runtime.NumCPU()) is the right answer.

Trigger 5: File descriptors¶

You are opening files or sockets in parallel. The OS limit is ulimit -n. Without a bound you hit EMFILE. With a bound of half the ulimit you stay safe.

Trigger 6: Steady high task rate over time¶

You serve a long-running service that handles thousands of tasks per second, every second, for hours. This is where pool reuse begins to matter — but even here, measure first. Most services at 1k–10k RPS do not need a third-party pool.

Trigger 7: Custom features¶

You need dynamic resize, runtime metrics on running workers, panic recovery without crashing the program, or non-blocking submit with a queue overflow handler. The standard library does not offer these; a third-party pool does.

For triggers 1–6, errgroup is the answer 90%+ of the time. Trigger 7 is where pools earn their keep.

Coding Patterns¶

Pattern: "Default to errgroup"¶

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(K)
for _, item := range items {
    item := item
    g.Go(func() error { return process(ctx, item) })
}
return g.Wait()

Memorise this. It is the answer 90% of the time. K is chosen by the scarcest downstream resource.

Pattern: "Token channel as a quick semaphore"¶

sem := make(chan struct{}, K)
var wg sync.WaitGroup
for _, item := range items {
    item := item
    wg.Add(1)
    sem <- struct{}{}
    go func() {
        defer wg.Done()
        defer func() { <-sem }()
        process(item)
    }()
}
wg.Wait()

This is what people wrote before errgroup.SetLimit existed. Still common in code without errgroup. The semantics are exactly the bound — no error propagation, no context.

Pattern: "Fixed worker pool with channels"¶

tasks := make(chan Task, 100)
var wg sync.WaitGroup
for i := 0; i < K; i++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        for t := range tasks {
            process(t)
        }
    }()
}

for _, t := range myTasks {
    tasks <- t
}
close(tasks)
wg.Wait()

A homemade pool. K long-lived workers, FIFO queue. About 12 lines. Fine when you specifically want this shape (workers persist, FIFO, you control the queue). The cost — being a homemade pool — is that you must remember to close the channel and to handle panics yourself.

Pattern: "Pipeline of pools"¶

stage1Out := make(chan A, 10)
stage2Out := make(chan B, 10)

g, ctx := errgroup.WithContext(ctx)

g.Go(func() error {
    defer close(stage1Out)
    return produce(ctx, stage1Out)
})

g.Go(func() error {
    defer close(stage2Out)
    subg, subctx := errgroup.WithContext(ctx)
    subg.SetLimit(5)
    for a := range stage1Out {
        a := a
        subg.Go(func() error {
            b, err := transform(subctx, a)
            if err == nil {
                stage2Out <- b
            }
            return err
        })
    }
    return subg.Wait()
})

g.Go(func() error { return consume(ctx, stage2Out) })

return g.Wait()

Pipelines often need different concurrency at each stage. Nested errgroups give you that without a third-party pool.

Pattern: "Don't bother — just spawn"¶

go logEverySecond()

There is no pool. There is no errgroup. There is one goroutine. This is correct.

Clean Code¶

A few rules of thumb that keep your concurrency code honest, even before you start arguing about pools.

Rule: One way to start a goroutine¶

A function should not sometimes spawn a goroutine and sometimes run sync. Either it returns a value, or it returns a channel/future. Mixing them is confusing.

Rule: Always have a story for stopping¶

For every goroutine you start, ask: how does it stop? "It returns when its function returns" is a fine answer. "When the context is cancelled" is a fine answer. "Never, because it loops forever" is a bug.

Rule: Pass ctx; do not capture it from outside¶

Long-running goroutines should accept a context as a parameter. Short-lived ones inside an errgroup share the errgroup's ctx. This makes cancellation paths clear.

Rule: Limit at the right place¶

If you have an HTTP handler that calls a downstream service, you can limit at the handler (max in-flight requests on your server) or at the call site (max in-flight downstream calls). Often both. The pool is just a place to enforce the limit; deciding which limit you are enforcing is more important than which tool you use.

Rule: Prefer code that reads top-to-bottom¶

A pool with a Submit(func()) and a separate result handler reads non-linearly: code dispatches now, returns later, somewhere else. errgroup.Go plus Wait reads linearly: you can see the bound, the body, and the result in one place. Lean on errgroup for linear code unless you need otherwise.

Rule: Comment the K¶

If you write SetLimit(50), leave a comment explaining why 50. "Downstream API limit per docs as of 2024-09-12" is a good comment. "Felt right" is a bad comment.

Error Handling¶

Errors from spawned tasks¶

Raw goroutines do not return errors. You must either:

• Capture errors into a slice indexed by goroutine
• Send errors to a channel
• Use errgroup, which does it for you

errs := make(chan error, len(items))
var wg sync.WaitGroup
for _, item := range items {
    item := item
    wg.Add(1)
    go func() {
        defer wg.Done()
        if err := process(item); err != nil {
            errs <- err
        }
    }()
}
wg.Wait()
close(errs)
for err := range errs {
    fmt.Println(err)
}

This is fine but verbose. errgroup collapses it to a few lines.

Panic recovery¶

A panic in a goroutine that does not recover kills the whole program. This is true of raw goroutines and of errgroup goroutines (errgroup does not recover for you). Third-party pools differ: ants has an Options.PanicHandler that catches panics so the worker survives.

If you want raw goroutines to survive panics:

go func() {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("worker panic: %v", r)
        }
    }()
    doRiskyWork()
}()

The same wrapper goes around errgroup.Go if you want it there too. The wrapper is small enough that "I need panic recovery" is not, by itself, a reason to adopt ants.

Cancellation¶

errgroup.WithContext is the simplest cancellation story: the first error cancels the shared context, all in-flight tasks see it (if they respect ctx), they return early. Raw goroutines and pools both make you wire this up by hand.

ctx, cancel := context.WithCancel(parent)
defer cancel()

go func() {
    if err := doWork(ctx); err != nil {
        cancel()
    }
}()

If you find yourself writing this wiring more than once, it is a sign you should be using errgroup.

Don't swallow errors silently¶

A common bug in pool-using code:

_ = pool.Submit(func() { process(item) })

process returns no error here, so an internal failure is silent. Make sure your task closure does something on error — log it, send to a channel, set a flag.

Performance Tips¶

For junior level, performance tips are mostly about not over-engineering. The specifics come later. These are the rules:

• Do not pool unless your benchmark says you should. Adding ants to a workload that handles 100 RPS will not make it faster; it will just add a dependency.
• Right-size the bound. A bound of 5 when the system can handle 50 leaves throughput on the table. A bound of 500 when the downstream allows 50 floods it. Tune based on real measurements.
• Avoid time.Sleep polling. If you find yourself sleeping in a loop to wait for a pool to drain, you should be using a WaitGroup or errgroup.
• Beware shared maps. When N goroutines write to the same map, you must sync.Mutex it. Forgetting this is the single most common bug at this level.
• Prefer batching over fine-grained pooling. If each task is tiny, batch them (process 100 at a time) before submitting to a pool. The goroutine overhead per micro-task dominates the work.

We will come back to performance with real numbers in senior.md.

Best Practices¶

• Start with no concurrency. Write the sequential version first. Concurrency is an optimisation — make sure the sequential code is correct first.
• Add concurrency in the smallest amount that helps. Often that is errgroup.SetLimit and nothing else.
• Justify every dependency. Adopting ants or tunny adds a third-party project to your audit surface. Have a reason in the commit message.
• Document the bound. Every K you pick should be paired with a comment about why.
• Always cancel. Every errgroup should have a ctx and every task should respect it.
• Always Wait. Forgetting g.Wait() is the same bug as forgetting wg.Wait() — your main goroutine exits before the work finishes.
• Don't leak goroutines. Every goroutine has a clear exit. Background loops have a stop channel or a ctx.
• Don't share state without sync. Even inside a "single-writer" pattern, write the test that proves the pattern.

Edge Cases & Pitfalls¶

Pitfall: "I'll add a pool, I'm sure it helps"¶

You don't know it helps. Measure first. The benchmark in tasks.md shows scenarios where the pool loses to raw goroutines because the pool's queue lock becomes the bottleneck.

Pitfall: Pool size = GOMAXPROCS for I/O-bound work¶

A common error. If your tasks block on I/O, GOMAXPROCS is the wrong K. The right K is the downstream service's limit, or the file-descriptor budget, not the number of CPU cores. CPU-bound work uses NumCPU(); I/O-bound work uses whatever the I/O sink supports.

Pitfall: Pool size > 1000 with no reason¶

A pool sized at 1000 is rarely necessary. If you need 1000 concurrent calls, you may not have a concurrency problem; you may have a throughput problem better solved by scaling out. Check before committing.

Pitfall: pool.Submit returns an error you ignore¶

Both ants and tunny can fail to accept a task (full queue, closed pool). Ignoring the error means silent dropped work. Always handle it.

if err := pool.Submit(work); err != nil {
    // log or fallback
}

Pitfall: Using a pool for a one-shot script¶

A pool's setup cost (a few microseconds, a few KB) is irrelevant in production. In a 200ms script, it is noise but pointless. If your program runs once and exits, do not pool unless the workload itself is huge.

Pitfall: Mixing pool and errgroup¶

You sometimes see code that calls pool.Submit(func() { g.Go(...) }). This is almost always wrong — you are pooling the outer layer and not bounding the inner. Pick one approach per layer.

Pitfall: Forgetting Release / closing the pool¶

A pool that you never release leaks workers when the program continues past the workload. defer pool.Release() next to the constructor is the standard guard. For tunny, it is defer pool.Close().

Pitfall: Blocking the producer when you didn't mean to¶

errgroup.SetLimit(K) makes g.Go block when K is reached. That is usually what you want. But if you call g.Go from a goroutine that also reads from a channel feeding the loop, you can deadlock when the consumer is blocked on the producer. Always reason about the back-pressure cycle.

Pitfall: Tasks that hold a lock¶

If each pooled task acquires the same lock, your effective concurrency is 1, regardless of pool size. The pool is not helping. Refactor to share less state, or you don't need the pool.

Pitfall: Bound chosen without context¶

A pool size of 100 means very different things on a laptop (8 cores) and on a 96-core server. Sometimes the right K is a function of the environment, not a constant. runtime.NumCPU() for CPU-bound work, an env-driven config for everything else.

Common Mistakes¶

Mistake 1: "Pools because pools"¶

You read a blog post that says pools are good. You add ants to a 50-line script. You feel professional. You added a dependency for nothing. Remove it.

Mistake 2: "Errgroup but no SetLimit"¶

Plain errgroup.Group without SetLimit is unbounded. It is WaitGroup with errors. People sometimes think errgroup bounds by default. It does not. You must call SetLimit.

Mistake 3: Putting SetLimit after Go¶

g.SetLimit must be called before any g.Go. Calling it after panics or no-ops depending on version. Always set the limit at construction time.

Mistake 4: Captured loop variable¶

for i := 0; i < 5; i++ {
    go func() { fmt.Println(i) }()
}

In Go ≤1.21, all five goroutines print 5. In Go 1.22+, each gets its own i. If you support older Go, always shadow: i := i.

Mistake 5: WaitGroup Add inside the goroutine¶

go func() {
    wg.Add(1)  // wrong
    defer wg.Done()
    work()
}()
wg.Wait()  // might race past Add

wg.Add must be called before the goroutine starts, otherwise Wait can race past it.

Mistake 6: Goroutines that never end¶

go func() {
    for {
        // no exit condition, no stop channel
    }
}()

A goroutine that does not end is a leak. Every long-running goroutine needs a stop story.

Mistake 7: Using ants for a workload with results¶

ants.Submit(func()) is fire-and-forget. If you want results back, you need to wire your own channel — at which point you might as well use tunny (which has Process returning a value) or errgroup.

Mistake 8: Adopting a library without reading its README¶

ants has options you must know about: WithNonblocking, WithMaxBlockingTasks, WithPanicHandler. Their defaults may surprise you. Read the docs before depending on the lib.

Mistake 9: Using a pool to "make it faster" without a benchmark¶

The pool may make it slower. The queue lock, the dispatch overhead, the worker park/wake — all of these have measurable costs. Always benchmark before and after.

Mistake 10: Sharing one global pool across the whole program¶

This is OK sometimes but often hides bugs: one heavy workload starves another. Pools are often better scoped to a request, a stage, or a feature. Global pools should be a deliberate choice, not a default.

Common Misconceptions¶

"Goroutines are so cheap I never need to limit them."¶

True at small scale. False at large scale. A million goroutines is 2 GB of stack and a busy scheduler. Limit when you need to, not before.

"Pools are faster than raw goroutines."¶

Sometimes. Often not. Raw go f() plus a small pool of warm workers can be slower under contention if the pool has lock-heavy dispatch. Measure.

"errgroup is just for errors."¶

Wrong; errgroup is also the standard answer for bounded concurrency, with SetLimit. Many engineers miss this and reach for a third-party pool when errgroup would have worked.

"Pools are required for production code."¶

False. Many production services use only the standard library. Pools are a tool, not a requirement.

"Bigger pools = more throughput."¶

Up to a point. Beyond the downstream limit, more workers just add contention and cancel each other out. The throughput curve flattens; in some cases it inverts.

"Pools fix slow code."¶

No. They give you control over how much runs at once. They do not make individual tasks faster. If each task takes 5 seconds, no pool will make it shorter.

"A pool lets me ignore goroutine leaks."¶

No. A pool with unbounded queue can leak tasks just as easily as raw go f() can leak goroutines. The leak is in your code; the pool does not fix it.

"SetLimit(1) is the same as sync.Mutex."¶

Almost, but not quite — SetLimit(1) queues tasks, mutex protects data. You can have many concurrent tasks all guarded by one mutex, or one serialised task that touches many things. Don't conflate them.

"I need a pool because my service uses CPU."¶

You need to pick the right K. The pool is one way to enforce K; errgroup.SetLimit(runtime.NumCPU()) is another and is simpler.

"Third-party pools are battle-tested, so I should trust them."¶

Trust them after you read their issues page, their commit history, and at least one real benchmark. ants is excellent and well-maintained; tunny is solid; workerpool is small and audited. But "third party" never means "free." You own everything you depend on.

Tricky Points¶

Tricky: errgroup.SetLimit(0)¶

SetLimit(0) means no goroutines allowed. It is not the same as "no limit." For no limit, do not call SetLimit. Calling SetLimit(-1) resets to unlimited (in current versions).

Tricky: errgroup.Go returns immediately when below the limit, blocks above¶

This is the bound. If you have 10 active and you call Go the 11th time with SetLimit(10), the call blocks until one finishes. That blocking is back-pressure. It is usually correct, but it means you cannot call g.Go from inside a goroutine that needs to finish first — risk of deadlock.

Tricky: errgroup does not have a "drain" method separate from Wait¶

Wait() waits for everything. There is no "wait for one." If you need that, you need a manual channel.

Tricky: ants.Submit returns nil even when the pool is at capacity in non-blocking mode by default¶

Wait, no — the default is blocking. In non-blocking mode (WithNonblocking(true)), Submit returns ErrPoolOverload instead of blocking. The default behavior is to block at submission. Always check the docs for the version you import.

Tricky: Pool size of 1¶

A pool of one worker serialises tasks. This is sometimes what you want (single-threaded queue with backpressure). But it makes the pool's overhead pointless; consider whether a channel + one goroutine is clearer.

Tricky: Pool size of runtime.GOMAXPROCS(0)¶

This reads the current GOMAXPROCS at construction time. If GOMAXPROCS changes (some systems alter it from a control loop), the pool does not auto-resize. Most pools have a Tune or Resize method for this.

Tricky: A pool inside an errgroup¶

You can do it but you usually do not need to. The pool bounds the workers; the errgroup bounds outer coordination. If both have limits, the smaller one wins. Usually pick one layer for bounding.

Test¶

Test 1: Spawn 5 goroutines, wait for all¶

Write a function that calls compute(i) for i in 0..4 in parallel and returns the slice of results. No pool. Just goroutines and WaitGroup.

func computeAll() [5]int {
    var results [5]int
    var wg sync.WaitGroup
    for i := 0; i < 5; i++ {
        i := i
        wg.Add(1)
        go func() {
            defer wg.Done()
            results[i] = compute(i)
        }()
    }
    wg.Wait()
    return results
}

Test 2: Fetch 100 URLs at most 10 at a time¶

Write a function that fetches a slice of URLs and returns the slice of HTTP status codes. Limit to 10 concurrent. Propagate errors.

func fetchAll(ctx context.Context, urls []string) ([]int, error) {
    codes := make([]int, len(urls))
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10)
    for i, u := range urls {
        i, u := i, u
        g.Go(func() error {
            req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
            if err != nil { return err }
            resp, err := http.DefaultClient.Do(req)
            if err != nil { return err }
            defer resp.Body.Close()
            codes[i] = resp.StatusCode
            return nil
        })
    }
    return codes, g.Wait()
}

Test 3: Process a stream from a channel, at most K at a time¶

Given in chan Job, process each job with handle(job) and limit to K concurrent.

func processStream(ctx context.Context, in <-chan Job, K int) error {
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(K)
    for {
        select {
        case <-ctx.Done():
            return g.Wait()
        case j, ok := <-in:
            if !ok {
                return g.Wait()
            }
            j := j
            g.Go(func() error { return handle(ctx, j) })
        }
    }
}

Test 4: When does a third-party pool win?¶

Describe one workload where a third-party pool (e.g., ants) beats errgroup.SetLimit. Hint: think about rate and worker reuse.

Test 5: Identify the wrong tool¶

A coworker writes a CLI that processes a directory of 200 image files, compressing each, and uses tunny.NewPool for it. What is wrong?

Test 6: What is K?¶

You are calling an internal microservice with a documented "max 25 in-flight per client" limit. Each call takes ~200 ms. You have 10 concurrent users. What K do you use, and at what layer?

Tricky Questions¶

Q: Why might SetLimit(1) and a mutex differ in behaviour?¶

SetLimit(1) queues tasks in submission order; a mutex grants first to arrive and there is no queue inside the mutex. Under heavy contention, mutex order is unpredictable; pool order is queue-based.

Q: Can you use errgroup for an infinite producer?¶

Yes, but you should bound it. errgroup does not have a "stop after N done" feature — it waits for every Go it has seen. For an infinite stream, the producer's exit is what ends the cycle. Use a select with ctx.Done() to break out.

Q: Is pool.Submit safe to call from many goroutines?¶

Yes, for ants, tunny, and workerpool — all three have thread-safe Submit. Always check the lib's docs, but the answer for popular libs is yes.

Q: If I have 8 CPUs and an I/O-bound workload, what is K?¶

K is not 8. K is whatever the downstream service (or file-descriptor budget) supports. Maybe 50, maybe 500. CPU is not the bottleneck for I/O-bound work.

Q: What happens when errgroup.SetLimit is at K and another goroutine in the program is blocked on the same downstream resource?¶

The errgroup does not know about the other goroutine. The actual concurrency hitting the downstream is K + (whatever else is running). If that matters, share a semaphore.Weighted across the entire program instead.

Q: Is "pool of 0 workers" valid?¶

In ants, no — Cap must be at least 1. In errgroup, calling SetLimit(0) is a hard block (no goroutines allowed). Both are usually a misconfiguration; check your K.

Cheat Sheet¶

==================== POOL DECISION CHEAT SHEET ====================

Step 1: Default to errgroup.

    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(K)
    for _, x := range xs {
        x := x
        g.Go(func() error { return work(ctx, x) })
    }
    return g.Wait()

Step 2: If errgroup doesn't fit, why not?

    - Need unequal weights        -> semaphore.Weighted
    - Need worker reuse           -> third-party pool
    - Need dynamic resize         -> third-party pool
    - Need panic recovery         -> wrap g.Go or use third-party
    - Need non-blocking submit    -> third-party pool (ants Nonblocking)
    - Need queue overflow drop    -> third-party pool
    - Spawn rate > 100k/s         -> third-party pool

Step 3: If raw goroutines are enough, use them.

    - Bounded by problem (small N)
    - One background task
    - Test/benchmark/CLI one-shot
    - No fan-out

==================== SIZING K ====================

CPU-bound:                runtime.NumCPU()
I/O-bound (network):      downstream's concurrency limit
Memory-bound:             memory budget / per-task footprint
File-bound:               ulimit -n / 2
Mixed:                    measure

==================== ANTI-PATTERNS ====================

- Pool added without measurement
- Pool size = GOMAXPROCS for network calls
- Pool with mutex inside every task (effective K = 1)
- Pool.Submit error ignored
- Pool never Released
- errgroup without SetLimit (unbounded!)
- SetLimit called after Go

==================== ONE-LINER VERDICTS ====================

- 5 tasks total                       -> raw goroutines
- 5000 tasks with errors and ctx      -> errgroup.SetLimit
- 5000 tasks, unequal weight          -> semaphore.Weighted
- Steady millions/sec, simple tasks   -> ants
- Worker-state-per-task workload      -> tunny
- Need FIFO and metrics               -> workerpool or pond

===================================================================

Self-Assessment Checklist¶

• I can explain in one sentence why errgroup.SetLimit is the default.
• I can write the same "fetch URLs, bounded" code in three styles.
• I can pick K based on the downstream limit, not GOMAXPROCS by default.
• I know that goroutines are cheap but not free.
• I can name three problems a third-party pool solves.
• I can name three situations where a pool would be overkill.
• I never reach for ants before reading its README.
• I always have a story for how each goroutine ends.
• I always pair errgroup with a ctx.
• I always Comment the K with a reason.
• I do not confuse "limit goroutines" with "limit anything-with-a-side-effect."
• I have read this file once and will reread it before my next concurrency PR.

If you can tick all 12, you are ready for middle.md.

Summary¶

• The Go runtime makes raw goroutines cheap, but not free.
• errgroup.SetLimit(K) is the default answer for "limit concurrent tasks with errors and ctx."
• semaphore.Weighted is the right answer when tasks have unequal weight.
• Third-party pools (ants, tunny, workerpool) are for the cases the standard library does not cover: high spawn rate, worker-reuse, special features.
• Most code does not need a third-party pool. Reaching for one first is a junior mistake.
• The decision tree is short: bounded by problem? raw. Need bound + errors? errgroup. Unequal weight? semaphore. Special features or extreme rate? third-party.
• Always measure before adopting a dependency. The cost of a dependency is real; the benefit must be measurable.
• Pool size K is chosen by the scarcest downstream resource, not by GOMAXPROCS by default.

What You Can Build¶

After mastering this material, you can build:

• A web crawler that fetches 10,000 URLs with a bound, propagates errors, and respects ctx cancellation.
• A batch image converter that processes a directory of files with K=NumCPU and one error channel.
• An API client that respects a downstream rate limit with semaphore.Weighted.
• A small CLI that you can confidently not add a pool to, because it is a one-shot script.
• A code reviewer's checklist for spotting unnecessary ants adoption in PRs.

Further Reading¶

• The standard library golang.org/x/sync README — covers errgroup, semaphore, and singleflight.
• go.dev/blog/pipelines — patterns of fan-out and fan-in with channels alone.
• ants README on GitHub — the lib's official docs, including non-blocking and panic-handler options.
• tunny README — short, opinionated; explains the worker-reuse model.
• workerpool README — minimal, illustrates the simplest pool shape.
• "Go Concurrency Patterns" talk by Rob Pike — the original framing, predates third-party pools.
• "Visualizing Concurrency in Go" by Ivan Daniluk — intuition for scheduler behaviour.

Related Topics¶

• 01-goroutines/01-overview — the basics of goroutines, prerequisite for everything here.
• 02-channels — coordination primitives that underlie pools.
• 06-context — the standard cancellation story used in errgroup.
• 17-goroutine-pools-3rd-party/01-overview — what a pool is.
• 17-goroutine-pools-3rd-party/02-ants — deep dive on ants.
• 17-goroutine-pools-3rd-party/03-tunny — deep dive on tunny.
• 15-concurrency-anti-patterns — what not to do, often complementary to "when to use a pool."

Diagrams & Visual Aids¶

Decision flowchart¶

                +------------------------+
                |  Concurrent workload?  |
                +-----------+------------+
                            |
                            v
              +-------------+--------------+
              | Bounded by the problem?    |
              | (small fixed N)            |
              +-----+---------------+------+
                Yes |               | No
                    v               v
            +-------+----+   +------+--------------------+
            | go f()     |   | Need error propagation?   |
            | + WG       |   +-------+---------------+---+
            +------------+       Yes |               | No
                                     v               v
                             +-------+-----+   +-----+----------------+
                             | errgroup    |   | Just spawn, log err? |
                             | SetLimit(K) |   | -> token chan + WG   |
                             +------+------+   +----------------------+
                                    |
                                    v
                         +----------+----------+
                         | Unequal task weight?|
                         +-----+---------+-----+
                           Yes |         | No
                               v         v
                       +-------+--+    +-+--------------------+
                       | semaphore |   | errgroup is enough?  |
                       | Weighted  |   +-+--------------------+
                       +-----------+     |
                                  Yes-> done
                                  No (need feature/scale)
                                     v
                              +------+-----------------+
                              | Third-party pool       |
                              | (ants/tunny/workerpool)|
                              +------------------------+

Concurrency vs throughput curve¶

Throughput
   |
   |             ***
   |          ***   ***
   |       ***         ***********  <- pool size doesn't help past here
   |    ***
   | ***
   +----------------------------------> Pool size K
   |
   |           ^
   |       sweet spot
   |

Cost-benefit grid¶

                Low Cost          High Cost
              +--------------+--------------+
   Low        |  raw         |  errgroup    |
   Benefit    |  goroutines  |  (overkill)  |
              +--------------+--------------+
   High       |  errgroup    |  ants/tunny  |
   Benefit    |  (default)   |  (special)   |
              +--------------+--------------+

The two boxes you want to live in are bottom-left (raw) and bottom-right (third-party with measured reason). The top-right is the trap.

The "what is the limit" tree¶

Limit Source             Tool                              K
-------------------------------------------------------------------
Downstream API           errgroup.SetLimit                 API's limit
CPU cores                errgroup.SetLimit                 runtime.NumCPU()
Memory budget            errgroup.SetLimit                 budget / footprint
File descriptors         semaphore.Weighted                ulimit -n / 2
Unequal task weight      semaphore.Weighted                varies
Spawn rate amortisation  third-party pool                  by load test
Worker-state-per-task    tunny                             worker count
Stream feeds at high rate ants                             by load test

This table is the most compact form of the decision. Memorise it; it covers most production cases.

Time-to-decision¶

0:00  "I need concurrency"
0:30  "Is N small and bounded? Yes -> raw."
1:00  "Errors and ctx? Yes -> errgroup.SetLimit"
2:00  "Unequal weights? Yes -> semaphore.Weighted"
3:00  "Extreme rate or features? Maybe -> third-party"
3:30  "Have I measured? No -> back to errgroup."
4:00  "Have I measured? Yes -> pick the right pool."

If you arrive at "third-party pool" in under 3 minutes you are probably skipping the questions. Slow down.

Deeper Walk-Through: The Four Patterns in Action¶

We have seen the decision tree. We have seen short examples. Let us now walk through a single concrete service problem and watch it evolve through all four patterns — raw, errgroup, semaphore, pool — and see exactly where each pattern shines.

The scenario: invoice PDF generator¶

You run an internal tool: a sales team uploads a CSV of orders, you produce a PDF invoice per row, you write each PDF to object storage, and you email the customer.

Per-row work:

1. Read row (cheap).
2. Render PDF (CPU-bound, ~300 ms per row).
3. Upload PDF to S3 (I/O-bound, ~100 ms).
4. Email customer (I/O-bound, ~50 ms).

A CSV usually has 5 to 5,000 rows. The S3 client supports up to 100 concurrent uploads. The SMTP server allows 20 concurrent connections. You run on a 4-core box.

This is a real-shaped problem. Let's see how the four patterns behave.

Pattern A: Sequential (no concurrency)¶

The first version anyone writes:

func processSequential(ctx context.Context, rows []Row) error {
    for _, r := range rows {
        pdf, err := renderPDF(r)
        if err != nil { return err }
        key, err := uploadPDF(ctx, pdf)
        if err != nil { return err }
        if err := sendEmail(ctx, r.CustomerEmail, key); err != nil {
            return err
        }
    }
    return nil
}

For 5 rows, total time ≈ 5 × (300 + 100 + 50) ms = 2.25 seconds. Acceptable.

For 5,000 rows, total time ≈ 5,000 × 450 ms = 37.5 minutes. Not acceptable.

The sequential version is the correctness baseline. Every concurrent version must produce the same output. Always have one available, even if just as a fallback.

Pattern B: Raw goroutines (no bound)¶

The naive concurrent first attempt:

func processRawUnbounded(ctx context.Context, rows []Row) error {
    var wg sync.WaitGroup
    errCh := make(chan error, len(rows))
    for _, r := range rows {
        r := r
        wg.Add(1)
        go func() {
            defer wg.Done()
            pdf, err := renderPDF(r)
            if err != nil { errCh <- err; return }
            key, err := uploadPDF(ctx, pdf)
            if err != nil { errCh <- err; return }
            if err := sendEmail(ctx, r.CustomerEmail, key); err != nil {
                errCh <- err
            }
        }()
    }
    wg.Wait()
    close(errCh)
    for err := range errCh { if err != nil { return err } }
    return nil
}

For 5 rows: 4 cores, 5 goroutines, PDF rendering parallelised across cores. Total ≈ 600 ms.

For 5,000 rows:

• 5,000 CPU-bound renders queue across 4 cores. The runtime serialises them, but the goroutine creation still happens immediately.
• 5,000 S3 uploads attempted at once. The HTTP client's connection pool runs out, requests time out, or the S3 service starts returning 503s.
• 5,000 SMTP connections requested. The SMTP server limits us to 20; the rest get refused.
• Memory: each in-flight render holds a PDF buffer (~500 KB) in memory. 5,000 × 500 KB = 2.5 GB. OOM on a 2 GB pod.

This is the catastrophic failure mode that the bound prevents.

Pattern C: Token-channel bound¶

Quick and dirty bound:

func processBounded(ctx context.Context, rows []Row, K int) error {
    sem := make(chan struct{}, K)
    var wg sync.WaitGroup
    errCh := make(chan error, len(rows))
    for _, r := range rows {
        r := r
        wg.Add(1)
        sem <- struct{}{}
        go func() {
            defer wg.Done()
            defer func() { <-sem }()
            pdf, err := renderPDF(r)
            if err != nil { errCh <- err; return }
            key, err := uploadPDF(ctx, pdf)
            if err != nil { errCh <- err; return }
            if err := sendEmail(ctx, r.CustomerEmail, key); err != nil {
                errCh <- err
            }
        }()
    }
    wg.Wait()
    close(errCh)
    for err := range errCh { if err != nil { return err } }
    return nil
}

With K=20 (the SMTP limit), 5,000 rows take roughly 5,000/20 × 450 ms = 112 seconds. Memory at any time: 20 × 500 KB = 10 MB. OOM problem gone.

But notice the limitation: one bound for everything. The 20 SMTP slots are also the 20 PDF render slots, which is silly when we have 4 cores and SMTP allows 20. We are starving the CPU.

Pattern D: Three errgroups, one per stage¶

We can do better by pipelining:

func processPipeline(ctx context.Context, rows []Row) error {
    type rendered struct { row Row; pdf []byte }
    type uploaded struct { row Row; key string }

    pdfs := make(chan rendered, 32)
    uploads := make(chan uploaded, 32)

    g, ctx := errgroup.WithContext(ctx)

    // Stage 1: render — CPU-bound, K = NumCPU
    g.Go(func() error {
        defer close(pdfs)
        sub, ctx := errgroup.WithContext(ctx)
        sub.SetLimit(runtime.NumCPU())
        for _, r := range rows {
            r := r
            sub.Go(func() error {
                pdf, err := renderPDF(r)
                if err != nil { return err }
                select {
                case pdfs <- rendered{r, pdf}:
                case <-ctx.Done(): return ctx.Err()
                }
                return nil
            })
        }
        return sub.Wait()
    })

    // Stage 2: upload — I/O bound to S3, K = 50
    g.Go(func() error {
        defer close(uploads)
        sub, ctx := errgroup.WithContext(ctx)
        sub.SetLimit(50)
        for r := range pdfs {
            r := r
            sub.Go(func() error {
                key, err := uploadPDF(ctx, r.pdf)
                if err != nil { return err }
                select {
                case uploads <- uploaded{r.row, key}:
                case <-ctx.Done(): return ctx.Err()
                }
                return nil
            })
        }
        return sub.Wait()
    })

    // Stage 3: email — I/O bound to SMTP, K = 20
    g.Go(func() error {
        sub, ctx := errgroup.WithContext(ctx)
        sub.SetLimit(20)
        for u := range uploads {
            u := u
            sub.Go(func() error {
                return sendEmail(ctx, u.row.CustomerEmail, u.key)
            })
        }
        return sub.Wait()
    })

    return g.Wait()
}

Now each stage uses the right K for its bottleneck:

• Stage 1: 4 workers, CPU-saturating, no more.
• Stage 2: 50 workers, S3-saturating but well within its limit.
• Stage 3: 20 workers, SMTP-saturating, exactly at limit.

5,000 rows on 4 cores: stage 1 is the bottleneck (CPU). 5,000 × 300 ms / 4 = 6.25 minutes. Stages 2 and 3 happen in parallel with stage 1, hidden under the CPU cost.

This pipeline of errgroups is the idiomatic shape for a real-world pipeline. It does not need a third-party pool. We are running thousands of tasks with proper bounds and proper error propagation. The standard library is enough.

Pattern E: When would ants help?¶

It does not help here. We have 5,000 tasks per invocation, run once when the user uploads a CSV. There is no warm state to reuse; the program is essentially a batch job. ants would just add a dependency and replace g.Go with pool.Submit.

ants would start to help if, for example, this were a long-running service receiving CSVs continuously at high rate, with each row arriving over a message queue, processed individually. Then the spawn-per-row cost would matter — but only at very high rates (tens of thousands of rows/sec), and you would notice that in your profile.

Pattern F: When would tunny help?¶

If renderPDF required warm state — say, a per-worker PDF engine with a compiled font cache and a context that took 200 ms to initialise — then having 4 warm tunny workers, each holding a reusable engine, would amortise that startup. errgroup would re-initialise the engine per task; tunny would not.

This is a real example of "worker reuse for warm state." Some PDF and image libraries genuinely have this property. Most do not.

Lesson from the walk-through¶

The decision is not "raw vs errgroup vs pool." The decision is "what is each stage bounded by, and what is the cheapest tool that enforces that bound?" In our pipeline, three stages have three different bounds, and three errgroups solve them. No pool was necessary. That is the typical case.

Common Question: "But what if my service grows?"¶

A frequent objection from juniors who want to use a pool today, "just in case" the service grows.

The objection is reasonable in shape but wrong in conclusion. Yes, services grow. Yes, premature optimisation is bad; premature de-optimisation (refusing useful tools) is also bad. The question is: which tool is "useful"?

Three observations push back on the "just in case" argument:

1. errgroup.SetLimit scales just fine. The standard library was not abandoned at 100 RPS. Production services handle thousands of RPS with errgroup alone. Growth from 100 to 5000 RPS does not change the answer.

2. Refactoring from errgroup to ants is a small change. Once you have the bound encoded in SetLimit(K), swapping to ants.Submit is a 20-line diff. The architecture does not change; only the dispatcher does. Don't bake in ants today to save a 20-line diff later.

3. The shape of the load matters more than the size. A 5x increase in steady-state RPS rarely changes the answer. A change from "smooth flow" to "spiky bursts of 100,000 in 2 seconds" does — and that is the moment to introduce a pool, after you have measured it.

So the right posture is: use errgroup now, monitor, and let the actual scaling problem tell you when (if ever) to introduce a third-party pool.

Anti-Pattern Gallery¶

A short catalog of pool-related anti-patterns we see in real code.

Anti-pattern 1: The cargo-cult pool¶

pool, _ := ants.NewPool(100)
defer pool.Release()
for _, x := range xs {
    pool.Submit(func() { doOnce(x) })
}

xs has 4 elements. The pool is overkill. Fix: 4 goroutines + WaitGroup.

Anti-pattern 2: The infinite-queue pool¶

pool, _ := ants.NewPool(10, ants.WithMaxBlockingTasks(0))

MaxBlockingTasks=0 means "block forever." Under bursty load, the queue grows without bound, memory grows, and you crash. Set a reasonable cap, or use non-blocking with a fallback.

Anti-pattern 3: The pool of pools¶

outer, _ := ants.NewPool(10)
inner, _ := ants.NewPool(50)
outer.Submit(func() {
    for _, x := range xs {
        inner.Submit(func() { work(x) })
    }
})

Two pools, two bounds, no clear meaning. If outer is 10 and inner is 50, what is the effective concurrency? Hard to reason about. Collapse to one pool.

Anti-pattern 4: The serialised pool¶

pool, _ := ants.NewPool(100)
var mu sync.Mutex
for _, x := range xs {
    pool.Submit(func() {
        mu.Lock()
        defer mu.Unlock()
        work(x)
    })
}

100 workers all serialised by one mutex. Effective concurrency is 1. The pool is wasted; either remove the mutex (if work is independent) or remove the pool (if it must serialise).

Anti-pattern 5: The shared global¶

var pool = mustNewPool(1000)

func handler1() { pool.Submit(work1) }
func handler2() { pool.Submit(work2) }

One global pool used by every handler. A burst on handler1 starves handler2. Better: per-handler pool, or semaphore.Weighted per resource.

Anti-pattern 6: The pool that forgot to drain¶

pool, _ := ants.NewPool(10)
for _, x := range xs {
    pool.Submit(work(x))
}
return // workers may still be running!

Submit is fire-and-forget. Without a WaitGroup or a drain loop, your function returns before tasks finish. Always pair Submit with a join.

Anti-pattern 7: The "let's add metrics" pool¶

You add ants because "we need to know how many tasks are running." But errgroup plus a prometheus.Gauge does the same with no dependency:

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(K)
for _, x := range xs {
    x := x
    g.Go(func() error {
        runningGauge.Inc()
        defer runningGauge.Dec()
        return work(ctx, x)
    })
}
return g.Wait()