
A `sync.WaitGroup` waits for a set of goroutines to complete. The main goroutine calls `Add` to set the number of goroutines to wait for, each goroutine calls `Done` when finished, and `Wait` blocks until the count reaches zero.

<ExamplePair>
<ExampleProse>

Call `wg.Add(1)` before launching each goroutine. Inside the goroutine, defer `wg.Done()` so the count decrements even if the goroutine panics. Call `wg.Wait()` to block until all goroutines finish.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
)

func worker(id int, wg *sync.WaitGroup) {
    defer wg.Done()
    fmt.Printf("worker %d starting\n", id)
    // simulate work
    fmt.Printf("worker %d done\n", id)
}

func main() {
    var wg sync.WaitGroup

    for i := 1; i <= 5; i++ {
        wg.Add(1)
        go worker(i, &wg)
    }

    wg.Wait()
    fmt.Println("all workers done")
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Pass `*sync.WaitGroup` by pointer - copying a WaitGroup after first use is undefined behavior and will cause incorrect counts. `wg.Add` can be called with counts greater than one if you know the total up front, but adding inside the goroutine races with `Wait`:

</ExampleProse>
<ExampleCode>

```go
// correct: Add before goroutine launch
wg.Add(1)
go func() {
    defer wg.Done()
    // ...
}()

// wrong: Add inside the goroutine may run after Wait
go func() {
    wg.Add(1)       // race: Wait may have already returned
    defer wg.Done()
}()
```

</ExampleCode>
</ExamplePair>

<InProduction>
Always pass `*sync.WaitGroup` by pointer - copying a WaitGroup after first use is a data race. The `defer wg.Done()` pattern ensures Done is called even if the goroutine panics. Add the count before launching the goroutine; adding inside the goroutine is a race.
</InProduction>


Use sync.WaitGroup to wait for a collection of goroutines to finish.

WaitGroups


Rate limiting controls how frequently an operation can proceed. Go's standard approach uses a `time.Ticker` as a simple token source, or the `golang.org/x/time/rate` package for full token-bucket semantics with burst support.

<ExamplePair>
<ExampleProse>

A basic rate limiter uses a ticker channel. Each tick grants permission for one request. The sender blocks until the next tick fires, naturally enforcing the rate.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    requests := make(chan int, 5)
    for i := 1; i <= 5; i++ {
        requests <- i
    }
    close(requests)

    // allow 1 request per 200ms
    limiter := time.NewTicker(200 * time.Millisecond)
    defer limiter.Stop()

    for req := range requests {
        <-limiter.C
        fmt.Println("request", req, time.Now().Format("15:04:05.000"))
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

For burst allowances, use `golang.org/x/time/rate`. A `Limiter` with rate `r` and burst `b` permits up to `b` events at once and then allows `r` events per second:

</ExampleProse>
<ExampleCode>

```go
import "golang.org/x/time/rate"

limiter := rate.NewLimiter(rate.Every(100*time.Millisecond), 3) // 10/s, burst of 3

for i := 0; i < 10; i++ {
    if err := limiter.Wait(ctx); err != nil {
        return err
    }
    process(i)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`limiter.Allow()` is non-blocking - useful when you want to drop rather than queue:

</ExampleProse>
<ExampleCode>

```go
if !limiter.Allow() {
    http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
    return
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The `time/rate` package implements a token bucket that supports burst allowances. Use it at the service boundary to protect downstream dependencies. For multi-instance deployments, local rate limiting is not sufficient - you need a distributed counter (Redis INCR with TTL, or a sidecar rate limiter like Envoy).
</InProduction>


Control the rate of operations using tickers and the golang.org/x/time/rate token bucket.

Rate Limiting


A worker pool bounds concurrency by fanning N worker goroutines out over a shared jobs channel. Workers pull jobs until the channel closes, results flow back on a results channel, and a `sync.WaitGroup` ensures clean shutdown.

<ExamplePair>
<ExampleProse>

Create a `jobs` channel and a `results` channel. Launch 3 workers each reading from `jobs`. Send 5 jobs, close the channel so workers know when to stop, then collect all results.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
    "time"
)

func worker(id int, jobs <-chan int, results chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()
    for j := range jobs {
        fmt.Printf("worker %d started job %d\n", id, j)
        time.Sleep(time.Second) // simulate work
        fmt.Printf("worker %d finished job %d\n", id, j)
        results <- j * 2
    }
}

func main() {
    const numWorkers = 3
    const numJobs = 5

    jobs := make(chan int, numJobs)
    results := make(chan int, numJobs)

    var wg sync.WaitGroup
    for w := 1; w <= numWorkers; w++ {
        wg.Add(1)
        go worker(w, jobs, results, &wg)
    }

    for j := 1; j <= numJobs; j++ {
        jobs <- j
    }
    close(jobs) // signal workers to stop after draining

    // close results once all workers are done
    go func() {
        wg.Wait()
        close(results)
    }()

    for r := range results {
        fmt.Println("result:", r)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

For pure fan-out with no results collection, skip the results channel and close when the WaitGroup finishes:

</ExampleProse>
<ExampleCode>

```go
var wg sync.WaitGroup
for w := 0; w < numWorkers; w++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        for job := range jobs {
            process(job)
        }
    }()
}
wg.Wait()
```

</ExampleCode>
</ExamplePair>

<InProduction>
The worker pool pattern bounds concurrency for CPU-bound or rate-limited work. Size the pool to the bottleneck: CPU-bound work should use `runtime.GOMAXPROCS(0)` workers; I/O-bound work (HTTP, DB calls) should be tuned empirically with load testing. A pool of 100 goroutines hitting a database with `max_connections = 20` will queue at the DB level anyway - size the pool to match external resource limits, not to "be safe with more threads."
</InProduction>


Fan out work across N goroutines reading from a shared jobs channel to bound concurrency.