
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


When multiple goroutines increment a plain integer at the same time, the result is wrong. This happens because `counter++` is not one operation -- it reads the current value, adds 1, then writes it back. Two goroutines can read the same value simultaneously and both write the same incremented result, effectively losing one increment. This is called a **race condition**.

<ExamplePair>
<ExampleProse>

Here is the broken version. Run it with `go run -race` and Go will report a data race. The final count will be less than 1000.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
)

func main() {
    counter := 0 // plain int, NOT safe for concurrent use

    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            counter++ // read-modify-write: not atomic
        }()
    }

    wg.Wait()
    fmt.Println("counter:", counter) // often less than 1000
}
```

</ExampleCode>
</ExamplePair>

The fix is to make each increment a single indivisible operation so no two goroutines can interfere with each other. The `sync/atomic` package provides exactly this. Go 1.19 added typed atomic types (`atomic.Int64`, `atomic.Uint64`) that are safer than the older function-based API.

<ExamplePair>
<ExampleProse>

Replace the plain `int` with `atomic.Int64`. The `Add` method increments in one uninterruptible step. `Load` reads the current value safely. The result is always exactly 1000.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
    "sync/atomic"
)

func main() {
    var counter atomic.Int64 // zero value is 0, ready to use

    var wg sync.WaitGroup
    for i := 0; i < 1000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            counter.Add(1) // atomic: always correct
        }()
    }

    wg.Wait()
    fmt.Println("counter:", counter.Load()) // always 1000
}
```

</ExampleCode>
</ExamplePair>

**Compare-and-swap (CAS)** is a more advanced atomic operation. It reads the current value, checks if it matches what you expect, and only if it does, swaps it with a new value -- all in one uninterruptible step. It returns `true` if the swap happened, `false` if something else already changed the value first.

A practical example: imagine 5 goroutines all try to claim a background job. Only one should win. You can't use a plain `if` check because two goroutines might both read `false` at the same instant and both think they claimed it. CAS prevents this -- only the goroutine that gets there first succeeds, and all others see the updated value and back off.

<ExamplePair>
<ExampleProse>

5 goroutines race to claim a job. Each calls `CompareAndSwap(false, true)` -- only the first one finds the flag still `false` and wins. The rest get `false` back and skip.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
    "sync/atomic"
)

func main() {
    var claimed atomic.Bool

    var wg sync.WaitGroup
    for i := 1; i <= 5; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            if claimed.CompareAndSwap(false, true) {
                fmt.Printf("goroutine %d claimed the job\n", id)
            } else {
                fmt.Printf("goroutine %d: already claimed, skipping\n", id)
            }
        }(i)
    }

    wg.Wait()
}
// exactly one goroutine prints "claimed the job"
// the rest print "already claimed, skipping"
```

</ExampleCode>
</ExamplePair>

`atomic.Pointer[T]` lets you swap out an entire struct pointer atomically. This is a common pattern for publishing updated configuration: writers store a new pointer, readers always load the latest one, and no mutex is needed.

<ExamplePair>
<ExampleProse>

The writer allocates a new `Config` and stores the pointer. Reader goroutines call `Load` and get either the old or new config -- never a half-written one.

</ExampleProse>
<ExampleCode>

```go
type Config struct{ MaxConns int }

var current atomic.Pointer[Config]

// writer: publish a new config snapshot
newCfg := &Config{MaxConns: 100}
current.Store(newCfg)

// reader: always gets a complete, consistent snapshot
cfg := current.Load()
fmt.Println(cfg.MaxConns)
```

</ExampleCode>
</ExamplePair>

<InProduction>
Atomic operations are cheaper than mutexes for simple counters and flags, but they do not compose. If you need to update two variables together as one unit, you need a mutex. The `sync/atomic` package is correct only for single-variable operations -- using it for multi-variable invariants is a common subtle bug.
</InProduction>


Use sync/atomic for lock-free single-variable operations across goroutines.

Atomic Counters


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.