These are the notes for Go episode 53. Raju's food app goes live. Its home page is built from three services with a WaitGroup, and when one fails the error silently disappears: errgroup brings it back, errgroup.WithContext cancels the other tasks on the first error, and SetLimit caps how many run at once. A tandoor with room for 10 kg leads to the weighted semaphore. When the price cache expires, a hundred customers make a hundred database calls, a thundering herd, until singleflight turns them into one. An SMS service that allows five messages a second answers 429 Too Many Requests until we rate limit with a time.Ticker and then a token bucket (rate.NewLimiter). A kitchen that takes orders ten times faster than it cooks grows an unbounded queue, fixed with a bounded channel: backpressure and load shedding. One channel can't broadcast news, so we build pub/sub with a broker. Finally, pressing Ctrl+C kills the program mid-order, until signal.NotifyContext gives us a graceful shutdown.
All outputs here are from real runs (Go 1.24.7, linux/amd64, a machine with 2 CPUs). Timings, counts that depend on timing, and the order of some lines change between runs.
Facts and sources
These come from the doc comments in the packages' own source code (golang.org/x/sync v0.19.0, golang.org/x/time v0.14.0, and the Go 1.24.7 standard library), read for this episode:
errgroup: "Package errgroup provides synchronization, error propagation, and Context cancellation for groups of goroutines working on subtasks of a common task." and "[errgroup.Group] is related to [sync.WaitGroup] but adds handling of tasks returning errors."errgroup.WithContext: "The derived Context is canceled the first time a function passed to Go returns a non-nil error or the first time Wait returns, whichever occurs first."Group.Wait: "blocks until all function calls from the Go method have returned, then returns the first non-nil error (if any) from them."Group.SetLimit: "limits the number of active goroutines in this group to at most n. A negative value indicates no limit."semaphore: "Package semaphore provides a weighted semaphore implementation."Acquire"acquires the semaphore with a weight of n, blocking until resources are available or ctx is done."singleflight: "provides a duplicate function call suppression mechanism."Domakes "sure that only one execution is in-flight for a given key at a time. If a duplicate comes in, the duplicate caller waits for the original to complete and receives the same results. The return value shared indicates whether v was given to multiple callers."rate.Limiter: "It implements a "token bucket" of size b, initially full and refilled at rate r tokens per second." "If no token is available, Allow returns false." "Wait blocks until one can be obtained or its associated context.Context is canceled." "Most callers should use Wait."os/signal: "The SIGINT signal is sent when the user at the controlling terminal presses the interrupt character, which by default is ^C (Control-C)." "A SIGHUP, SIGINT, or SIGTERM signal causes the program to exit." "The signals SIGKILL and SIGSTOP may not be caught by a program."signal.NotifyContextis listed in Go'sapi/go1.16.txt, so it arrived in Go 1.16.
Packages from golang.org/x
The standard library is the set of packages that comes with Go (fmt, sync, context, time, ...). The golang.org/x/... packages are extra packages written by the Go team, but downloaded separately, like an add-on. Today we use two of these modules (a module is a versioned collection of packages with a go.mod file, episode 2):
golang.org/x/sync:errgroup,semaphore,singleflightgolang.org/x/time:rate
You add one to your project with go get. This is the real output of go get golang.org/x/sync@v0.19.0 in a fresh module:
go: added golang.org/x/sync v0.19.0
and go.mod gains a require line, which says "this module needs that module, at that version":
module shop
go 1.24
require golang.org/x/sync v0.19.0
In the video, the programs that use these packages carry their go.mod at the bottom and run with go run . (run the package in the current folder).
errgroup: errors from many goroutines
| On the home page | In Go |
|---|---|
| three services: menu, offers, reviews | three goroutines |
| fetch them all at once | go + sync.WaitGroup |
| offers is down, the box is empty | the error is thrown away |
| wait for all and get the error | errgroup.Group |
A service here means a separate program the app asks for data over the network. We simulate one with fetch, which sleeps and then returns data or an error.
The obvious way: a WaitGroup
package main
import (
"errors"
"fmt"
"sync"
"time"
)
// three services build Raju's app home page
func fetch(name string, d time.Duration, fail bool) (string, error) {
time.Sleep(d)
if fail {
return "", errors.New(name + " service is down")
}
return name + " ok", nil
}
func main() {
var wg sync.WaitGroup
var menu, offers, reviews string
wg.Add(3)
go func() { defer wg.Done(); menu, _ = fetch("menu", 30*time.Millisecond, false) }()
go func() { defer wg.Done(); offers, _ = fetch("offers", 10*time.Millisecond, true) }()
go func() { defer wg.Done(); reviews, _ = fetch("reviews", 50*time.Millisecond, false) }()
wg.Wait() // waits... but where did the error go?
fmt.Printf("menu=%q offers=%q reviews=%q\n", menu, offers, reviews)
fmt.Println("home page ready!")
}
Real output:
menu="menu ok" offers="" reviews="reviews ok"
home page ready!
Why it fails: a goroutine started with go can't return a value, and a WaitGroup only counts goroutines: it has nowhere to put an error. So the error is dropped (_) and the page says it's ready with an empty box.
The fix: errgroup.Group
errgroup.Group is a WaitGroup for tasks that return an error. g.Go(f) runs f (a func() error) in a new goroutine and counts it; g.Wait() waits for all of them and returns the first non-nil error, or nil. The zero value var g errgroup.Group is ready to use, with no limit and no cancellation.
main.go:
package main
import (
"errors"
"fmt"
"time"
"golang.org/x/sync/errgroup"
)
func fetch(name string, d time.Duration, fail bool) (string, error) {
time.Sleep(d)
if fail {
return "", errors.New(name + " service is down")
}
return name + " ok", nil
}
func main() {
var g errgroup.Group // like a WaitGroup, but each task returns an error
var menu, offers, reviews string
g.Go(func() (err error) { menu, err = fetch("menu", 30*time.Millisecond, false); return })
g.Go(func() (err error) { offers, err = fetch("offers", 10*time.Millisecond, true); return })
g.Go(func() (err error) { reviews, err = fetch("reviews", 50*time.Millisecond, false); return })
if err := g.Wait(); err != nil { // the first error, after ALL tasks finish
fmt.Println("cannot build the page:", err)
return
}
fmt.Println("home page ready!", menu, offers, reviews)
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output:
$ go run .
cannot build the page: offers service is down
The function literals use a named result (err error) and a naked return (episode 9), so menu, err = fetch(...) sets both the outer variable and the error.
errgroup.WithContext: fail fast
With a plain group, Wait still waits for every task, even after one has failed and the work is pointless. errgroup.WithContext(parent) returns a group and a context; the context is cancelled the moment any task returns an error (or when Wait returns). Tasks must check the context, here with select, for this to help. Stopping all work as soon as one part fails is called failing fast.
main.go:
package main
import (
"context"
"errors"
"fmt"
"time"
"golang.org/x/sync/errgroup"
)
func fetch(ctx context.Context, name string, d time.Duration, fail bool) error {
select {
case <-time.After(d): // the work takes d...
case <-ctx.Done(): // ...unless the group gave up
fmt.Println(name, "stopped early:", ctx.Err())
return ctx.Err()
}
if fail {
return errors.New(name + " service is down")
}
fmt.Println(name, "finished")
return nil
}
func main() {
start := time.Now()
g, ctx := errgroup.WithContext(context.Background())
g.Go(func() error { return fetch(ctx, "menu", 300*time.Millisecond, false) })
g.Go(func() error { return fetch(ctx, "offers", 10*time.Millisecond, true) })
g.Go(func() error { return fetch(ctx, "reviews", 2*time.Second, false) })
err := g.Wait()
fmt.Println("error:", err)
fmt.Println("gave up after", time.Since(start).Round(10*time.Millisecond))
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output (the order of the first two lines changes between runs):
$ go run .
reviews stopped early: context canceled
menu stopped early: context canceled
error: offers service is down
gave up after 10ms
SetLimit and TryGo
g.SetLimit(n) allows at most n active goroutines in the group; g.Go blocks until there is room. g.TryGo(f) starts f only if there is room right now, and returns false instead of waiting.
main.go:
package main
import (
"fmt"
"sync"
"time"
"golang.org/x/sync/errgroup"
)
func main() {
var mu sync.Mutex
active, most := 0, 0
var g errgroup.Group
g.SetLimit(3) // at most 3 uploads at the same time
for i := 1; i <= 20; i++ { // 20 dish photos to upload
g.Go(func() error { // blocks while 3 are already running
mu.Lock()
active++
most = max(most, active)
mu.Unlock()
time.Sleep(20 * time.Millisecond) // uploading photo i
mu.Lock()
active--
mu.Unlock()
return nil
})
}
fmt.Println("error:", g.Wait())
fmt.Println("most uploads at once:", most)
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output:
$ go run .
error: <nil>
most uploads at once: 3
So an errgroup gives you three things in one: waiting, the first error, and a limit. It replaces the hand-made semaphore from episode 52 in most code.
Weighted semaphores
| In Raju's tandoor | In Go |
|---|---|
| holds 10 kg in total | semaphore.NewWeighted(10) |
| a party biryani takes 6 kg, a naan 1 kg | Acquire(ctx, 6), Acquire(ctx, 1) |
| take it out, the room is free | Release(6) |
A weighted semaphore is a semaphore where each task asks for a different amount of the resource, its weight. Acquire(ctx, n) takes n units or waits until there are enough (or ctx is done, then it returns ctx.Err()); Release(n) gives them back; TryAcquire(n) takes them only if they're free right now and never waits.
main.go:
package main
import (
"context"
"fmt"
"sync"
"time"
"golang.org/x/sync/semaphore"
)
func main() {
ctx := context.Background()
oven := semaphore.NewWeighted(10) // the tandoor holds 10 kg in total
orders := []struct {
name string
kg int64
}{{"party biryani", 6}, {"naan", 1}, {"chicken", 4}, {"paneer", 3}, {"naan", 1}}
var wg sync.WaitGroup
start := time.Now()
for _, o := range orders {
wg.Add(1)
go func() {
defer wg.Done()
if err := oven.Acquire(ctx, o.kg); err != nil { // wait for o.kg of room
return
}
defer oven.Release(o.kg) // give the room back
fmt.Printf("%3dms in: %-13s (%d kg)\n", time.Since(start).Milliseconds()/10*10, o.name, o.kg)
time.Sleep(50 * time.Millisecond)
}()
time.Sleep(time.Millisecond) // orders arrive one after another
}
wg.Wait()
fmt.Println("try 11 kg at once:", oven.TryAcquire(11))
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output (the order of the three 50 ms lines changes between runs):
$ go run .
0ms in: party biryani (6 kg)
0ms in: naan (1 kg)
50ms in: naan (1 kg)
50ms in: paneer (3 kg)
50ms in: chicken (4 kg)
try 11 kg at once: false
At 0 ms the biryani (6) and a naan (1) are in: 7 kg. The chicken needs 4 but only 3 are free, so it waits. The paneer (3) would fit, but the semaphore serves waiters in order (first in, first out), so it waits behind the chicken: a big request is never starved by a stream of small ones. TryAcquire(11) is false: more than the whole oven.
singleflight: one call for many callers
| At lunchtime | In Go |
|---|---|
| the price lives in a slow database | priceFromDB takes 50 ms |
| a cache keeps a copy for a minute | fast reads |
| the copy expires, 100 customers ask at once | 100 database calls |
| one person asks, tells everyone waiting | singleflight.Group |
A cache is a fast store of recent answers, so you don't ask the slow source every time. Its entries expire after a while so the data stays fresh. When an entry expires and a crowd of requests misses it at the same instant, they all hit the slow source together: a thundering herd, also called a cache stampede.
The obvious way
package main
import (
"fmt"
"sync"
"sync/atomic"
"time"
)
var dbCalls atomic.Int64
// the slow way to get today's thali price: ask the database
func priceFromDB() int {
dbCalls.Add(1)
time.Sleep(50 * time.Millisecond)
return 180
}
func main() {
var wg sync.WaitGroup
for i := 0; i < 100; i++ { // the cache just expired, and 100 customers open the app
wg.Add(1)
go func() {
defer wg.Done()
priceFromDB()
}()
}
wg.Wait()
fmt.Println("customers: 100, database calls:", dbCalls.Load())
}
Real output:
customers: 100, database calls: 100
The fix: singleflight.Do
sf.Do(key, fn) runs fn for a key (a name for the question) only if no call for that key is already running. Callers that arrive while it runs wait and get the same result. The third result, shared, is true when the value went to more than one caller (including the one whose call ran).
main.go:
package main
import (
"fmt"
"sync"
"sync/atomic"
"time"
"golang.org/x/sync/singleflight"
)
var dbCalls atomic.Int64
func priceFromDB() (any, error) {
dbCalls.Add(1)
time.Sleep(50 * time.Millisecond)
return 180, nil
}
func main() {
var sf singleflight.Group
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
wg.Add(1)
go func() {
defer wg.Done()
// same key at the same time: only ONE call runs, everyone gets its answer
v, _, shared := sf.Do("thali-price", priceFromDB)
if i == 0 {
fmt.Println("customer 0 got", v, "shared:", shared)
}
}()
}
wg.Wait()
fmt.Println("customers: 100, database calls:", dbCalls.Load())
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output:
$ go run .
customer 0 got 180 shared: true
customers: 100, database calls: 1
singleflight is not a cache: it only joins calls that overlap in time. Once the call returns, the next Do runs fn again. Use it in front of the code that refills a cache. DoChan is the same but returns a channel, and Forget(key) makes the next call start fresh.
Rate limiting
Rate limiting means controlling how many events happen per unit of time, for example "at most 5 SMS a second". Many services enforce a limit and answer HTTP 429 Too Many Requests when you go over it. Limiting on your side means your requests are not rejected.
The obvious way: send as fast as you can
smsAPI below pretends to be an SMS service with a limit of 5 messages in any one second, the way real services behave.
package main
import (
"fmt"
"time"
)
// the SMS company allows 5 messages a second; more and it answers 429 Too Many Requests
type smsAPI struct{ sent []time.Time }
func (a *smsAPI) send(n int) string {
now := time.Now()
recent := 0
for _, t := range a.sent {
if now.Sub(t) < time.Second {
recent++
}
}
if recent >= 5 {
return fmt.Sprintf("sms %2d: 429 Too Many Requests", n)
}
a.sent = append(a.sent, now)
return fmt.Sprintf("sms %2d: sent", n)
}
func main() {
api := &smsAPI{}
for i := 1; i <= 8; i++ { // 8 order-ready messages, as fast as we can
fmt.Println(api.send(i))
}
}
Real output:
sms 1: sent
sms 2: sent
sms 3: sent
sms 4: sent
sms 5: sent
sms 6: 429 Too Many Requests
sms 7: 429 Too Many Requests
sms 8: 429 Too Many Requests
A steady pace: time.Ticker
A ticker (time.NewTicker(d)) puts a value on its channel C every d, like a metronome. Waiting for a tick before each message gives a steady rate. Always Stop a ticker you no longer need.
package main
import (
"fmt"
"time"
)
func main() {
start := time.Now()
tick := time.NewTicker(200 * time.Millisecond) // a beat every 200ms = 5 a second
defer tick.Stop()
for i := 1; i <= 8; i++ {
<-tick.C // wait for the next beat
fmt.Printf("sms %d sent at %4dms\n", i, time.Since(start).Round(10*time.Millisecond).Milliseconds())
}
}
Real output:
sms 1 sent at 200ms
sms 2 sent at 400ms
sms 3 sent at 600ms
sms 4 sent at 800ms
sms 5 sent at 1000ms
sms 6 sent at 1200ms
sms 7 sent at 1400ms
sms 8 sent at 1600ms
The ticker can't "save up": even the first message waits 200 ms, although nothing was sent for a while.
Bursts allowed: the token bucket
| At the counter | In golang.org/x/time/rate |
|---|---|
| a jar holds at most 3 tokens, and starts full | burst = 3 |
| a new token drops in 5 times a second | rate (rate.Limit) = 5 per second |
| every SMS needs a token; none: wait, or give up | Wait(ctx) / Allow() |
A token bucket allows short bursts (as many events at once as the bucket holds) while keeping the long-run average at the rate. rate.NewLimiter(r, b) makes one with rate r tokens per second and size b. Wait(ctx) takes a token or blocks until one arrives (or ctx is done); Allow() takes one only if available right now, and never waits; Reserve() returns a reservation and how long to wait. rate.Every(200*time.Millisecond) converts an interval to a rate.
main.go:
package main
import (
"context"
"fmt"
"time"
"golang.org/x/time/rate"
)
func main() {
start := time.Now()
// a token bucket: refills 5 tokens a second, holds at most 3
lim := rate.NewLimiter(5, 3)
ctx := context.Background()
for i := 1; i <= 8; i++ {
if err := lim.Wait(ctx); err != nil { // take a token, or wait for one
return
}
fmt.Printf("sms %d sent at %4dms\n", i, time.Since(start).Round(10*time.Millisecond).Milliseconds())
}
fmt.Println("token free right now?", lim.Allow()) // Allow never waits
}
go.mod:
module shop
go 1.24
require golang.org/x/time v0.14.0
Commands:
$ go run .
Real output:
$ go run .
sms 1 sent at 0ms
sms 2 sent at 0ms
sms 3 sent at 0ms
sms 4 sent at 200ms
sms 5 sent at 400ms
sms 6 sent at 600ms
sms 7 sent at 800ms
sms 8 sent at 1000ms
token free right now? false
Concurrency limit or rate limit?
| Limits | Tools | Example |
|---|---|---|
| how many at once (concurrency) | errgroup.SetLimit, semaphore.Weighted, make(chan struct{}, N), worker pools |
3 uploads at a time |
| how often (rate) | time.Ticker, rate.NewLimiter |
5 SMS per second |
Real services often need both.
Backpressure and load shedding
The obvious way: an unbounded queue
The app takes an order every millisecond; the cook needs 10 ms per order. A slice that grows forever is an unbounded queue.
package main
import (
"fmt"
"sync"
"time"
)
func main() {
var mu sync.Mutex
var queue []int // orders waiting: a slice that can grow forever
done := make(chan struct{})
go func() { // the cook: one order every 10ms
for {
select {
case <-done:
return
default:
}
mu.Lock()
if len(queue) > 0 {
queue = queue[1:]
}
mu.Unlock()
time.Sleep(10 * time.Millisecond)
}
}()
for sec := 1; sec <= 5; sec++ { // the app takes an order every 1ms
for i := 0; i < 100; i++ {
mu.Lock()
queue = append(queue, i)
mu.Unlock()
time.Sleep(time.Millisecond)
}
mu.Lock()
fmt.Printf("after %3d orders: %3d waiting\n", sec*100, len(queue))
mu.Unlock()
}
close(done)
}
Real output (the numbers change a little between runs):
after 100 orders: 89 waiting
after 200 orders: 178 waiting
after 300 orders: 268 waiting
after 400 orders: 355 waiting
after 500 orders: 444 waiting
Why it fails: when the producer (the code making work) is faster than the consumer (the code doing it), a queue with no limit doesn't fix anything; it hides the overload while memory and waiting time grow without limit.
The fix: a bounded channel
| In Raju's kitchen | In Go |
|---|---|
| the rail holds 10 slips | make(chan int, 10): a bounded buffer |
| rail full: the waiter must stop | backpressure: a send on a full channel blocks |
| "kitchen busy, try in a minute", said right away | load shedding: select with default |
Backpressure is the slow part of a system pushing back on the fast part and slowing it down. A full channel gives it for free: the send blocks. Load shedding is refusing extra work on purpose, so the work you accept still goes well.
package main
import (
"fmt"
"time"
)
func main() {
orders := make(chan int, 10) // the order rail holds at most 10 slips
go func() { // the cook: one order every 10ms
for range orders {
time.Sleep(10 * time.Millisecond)
}
}()
accepted, busy := 0, 0
for i := 1; i <= 500; i++ { // the app takes an order every 1ms
select {
case orders <- i: // room on the rail: accept
accepted++
default: // rail full: say so now, don't pile up
busy++
}
time.Sleep(time.Millisecond)
}
fmt.Println("accepted:", accepted, " told 'kitchen busy, try in a minute':", busy)
fmt.Println("waiting on the rail, never more than:", cap(orders))
}
Real output (the split changes a little between runs):
accepted: 62 told 'kitchen busy, try in a minute': 438
waiting on the rail, never more than: 10
Without the default case, orders <- i would block instead: the app would slow down to the kitchen's speed (pure backpressure). Either way the queue has a bound.
Pub/sub
The obvious way: one channel, many listeners
package main
import (
"fmt"
"sync"
)
func main() {
news := make(chan string)
var wg sync.WaitGroup
for _, who := range []string{"waiter", "cashier", "delivery"} {
wg.Add(1)
go func() { // three listeners on ONE channel
defer wg.Done()
for m := range news {
fmt.Println(who, "heard:", m)
}
}()
}
news <- "paneer is sold out"
news <- "kitchen closes at 11"
news <- "new dish: mango lassi"
close(news)
wg.Wait()
}
Real output (which listener gets which message changes between runs):
delivery heard: paneer is sold out
delivery heard: kitchen closes at 11
delivery heard: new dish: mango lassi
Why it fails: a channel gives each value to exactly one receiver (fan-out, episode 52). Great for sharing work, wrong for news that everyone must hear.
The fix: a broker with a channel per subscriber
| In the staff group chat | In Go |
|---|---|
| the manager posts a message | the publisher: Publish(m) |
| every member gets a copy on their own phone | subscribers, one channel each |
| the app in the middle delivers to all | the broker |
Publish-subscribe (pub/sub) is a pattern where publishers send messages to a broker and every subscriber gets its own copy. The select with default in Publish drops a message for a subscriber whose buffer is full, so one slow subscriber can't block everyone (load shedding again).
package main
import (
"fmt"
"sync"
)
// a broker keeps one channel per subscriber
type Broker struct {
mu sync.Mutex
subs []chan string
}
func (b *Broker) Subscribe() <-chan string {
b.mu.Lock()
defer b.mu.Unlock()
ch := make(chan string, 8) // each subscriber: its own small buffer
b.subs = append(b.subs, ch)
return ch
}
func (b *Broker) Publish(m string) {
b.mu.Lock()
defer b.mu.Unlock()
for _, ch := range b.subs { // a copy for EVERY subscriber
select {
case ch <- m:
default: // a slow subscriber must not block everyone
fmt.Println("dropped for a slow subscriber:", m)
}
}
}
func main() {
var b Broker
var wg sync.WaitGroup
for _, who := range []string{"waiter", "cashier", "delivery"} {
ch := b.Subscribe()
wg.Add(1)
go func() {
defer wg.Done()
for m := range ch {
fmt.Println(who, "heard:", m)
}
}()
}
b.Publish("paneer is sold out")
b.Publish("kitchen closes at 11")
for _, ch := range b.subs { // closing time: close every subscriber's channel
close(ch)
}
wg.Wait()
}
Real output (the order between listeners changes between runs):
delivery heard: paneer is sold out
delivery heard: kitchen closes at 11
cashier heard: paneer is sold out
cashier heard: kitchen closes at 11
waiter heard: paneer is sold out
waiter heard: kitchen closes at 11
Big systems use the same idea between machines, with a separate broker program in the middle.
Graceful shutdown
A signal is a short message the operating system delivers to a program. Pressing Ctrl+C in a terminal sends SIGINT (the interrupt signal). SIGTERM is the polite "please stop" request other programs send; it is the default signal of the kill command. By default both make a Go program exit immediately. SIGKILL and SIGSTOP can never be caught.
The obvious way: no signal handling
The goroutine sends SIGINT to the program itself after 120 ms, standing in for Raju's finger on Ctrl+C.
package main
import (
"fmt"
"os"
"syscall"
"time"
)
func main() {
// pretend the owner presses Ctrl+C after 120ms
go func() { time.Sleep(120 * time.Millisecond); syscall.Kill(os.Getpid(), syscall.SIGINT) }()
for order := 1; order <= 5; order++ {
fmt.Println("cooking order", order, "...")
time.Sleep(50 * time.Millisecond) // halfway through cooking...
fmt.Println("order", order, "served")
}
fmt.Println("kitchen closed cleanly")
}
Real output:
cooking order 1 ...
order 1 served
cooking order 2 ...
order 2 served
cooking order 3 ...
signal: interrupt
The program died in the middle of order 3. go run reports how its child process ended: signal: interrupt.
The fix: signal.NotifyContext
signal.NotifyContext(parent, signals...) returns a context that is cancelled when one of the signals arrives, instead of the program exiting, plus a stop function that restores the default behaviour (so a second Ctrl+C kills the program) and frees resources. Check ctx.Done() between units of work.
package main
import (
"context"
"fmt"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
// ctx is cancelled when Ctrl+C (SIGINT) or SIGTERM arrives
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
go func() { time.Sleep(120 * time.Millisecond); syscall.Kill(os.Getpid(), syscall.SIGINT) }()
for order := 1; order <= 5; order++ {
select {
case <-ctx.Done(): // checked BETWEEN orders, never in the middle of one
fmt.Println("signal received:", ctx.Err())
fmt.Println("no new orders; saving the day's bill...")
fmt.Println("kitchen closed cleanly")
return
default:
}
fmt.Println("cooking order", order, "...")
time.Sleep(50 * time.Millisecond)
fmt.Println("order", order, "served")
}
}
Real output:
cooking order 1 ...
order 1 served
cooking order 2 ...
order 2 served
cooking order 3 ...
order 3 served
signal received: context canceled
no new orders; saving the day's bill...
kitchen closed cleanly
A graceful shutdown is: stop taking new work, finish the work in hand, clean up (save, flush, close), then exit normally. A web server does the same with http.Server's Shutdown method, later in the course. Give the clean-up a deadline (context.WithTimeout, episode 51), because a program that never finishes stopping may be killed for real.
signal (SIGINT / SIGTERM) → ctx cancelled → stop taking work → finish + clean up → exit 0
Mini project: the order service
Build Raju's order service:
- Orders go into a bounded rail (capacity 20); reply "busy" when it's full.
- Four cooks run in an
errgroupwithWithContext; a burnt dish is an error that stops the shift. - Every "order ready" SMS goes through
rate.NewLimiter(5, 3). - The price lookup goes through
singleflight. - On Ctrl+C, the cooks finish the dishes in hand, then the program exits cleanly.
Solution
main.go:
package main
import (
"context"
"errors"
"fmt"
"os"
"os/signal"
"sync/atomic"
"syscall"
"time"
"golang.org/x/sync/errgroup"
"golang.org/x/sync/singleflight"
"golang.org/x/time/rate"
)
var dbCalls atomic.Int64
var sf singleflight.Group
func price() int {
v, _, _ := sf.Do("thali", func() (any, error) {
dbCalls.Add(1)
time.Sleep(20 * time.Millisecond)
return 180, nil
})
return v.(int)
}
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
// pretend Raju presses Ctrl+C after 700ms
go func() { time.Sleep(700 * time.Millisecond); syscall.Kill(os.Getpid(), syscall.SIGINT) }()
rail := make(chan int, 20)
sms := rate.NewLimiter(5, 3)
var busy, sent atomic.Int64
// the front desk: an order every 5ms; when the rail is full, say "busy"
go func() {
defer close(rail)
for id := 1; ; id++ {
select {
case <-ctx.Done():
return // shutting down: no new orders
case rail <- id:
default:
busy.Add(1)
}
time.Sleep(5 * time.Millisecond)
}
}()
g, gctx := errgroup.WithContext(ctx)
for cook := 1; cook <= 4; cook++ {
g.Go(func() error {
for id := range rail { // ends when the desk closes the rail
time.Sleep(30 * time.Millisecond) // cooking (always finished)
if id == 1000 {
return errors.New("order 1000 burnt") // stops the whole shift
}
_ = price()
if err := sms.Wait(gctx); err == nil {
sent.Add(1)
}
}
return nil
})
}
err := g.Wait()
fmt.Println("shift error:", err)
fmt.Println("SMS sent:", sent.Load(), " told busy:", busy.Load() > 0)
fmt.Println("database calls for the price:", dbCalls.Load())
fmt.Println("kitchen closed cleanly")
}
go.mod:
module shop
go 1.24
require (
golang.org/x/sync v0.19.0
golang.org/x/time v0.14.0
)
Commands:
$ go run .
Real output:
$ go run .
shift error: <nil>
SMS sent: 6 told busy: true
database calls for the price: 11
kitchen closed cleanly
The numbers depend on timing. In 0.7 s the token bucket allows its burst of 3 plus about 5 a second, and after Ctrl+C sms.Wait(gctx) returns an error at once, so no more SMS are sent. singleflight only joins calls that overlap in time, so cooks asking at different moments each reach the database. Order 1000 is never reached, so the shift ends without an error, and the deferred close(rail) lets every cook's range finish.
Common mistakes (and the real messages)
| Mistake | Real message / result | Why | Fix |
|---|---|---|---|
errors dropped inside wg goroutines |
home page ready! with offers="" |
a WaitGroup has no errors |
errgroup.Group |
WithContext, but tasks ignore ctx |
Wait still takes the full 2 s |
cancelling is only a signal | select on ctx.Done() |
Acquire(ctx, n) with n bigger than the size |
waits until ctx is done: context deadline exceeded |
can never fit | check n <= size |
Acquire without Release |
everyone else waits forever | the room never comes back | defer sem.Release(n) |
| an unbounded queue | hundreds waiting, and growing | the producer is faster | a bounded channel |
| one channel for news | each message reaches one listener | a value goes to one receiver | a channel per subscriber |
| no signal handling | signal: interrupt mid-order |
the default is to exit | signal.NotifyContext |
forgetting stop() / tick.Stop() |
resources kept | they hold a registration / timer | defer stop(), defer tick.Stop() |
The real run behind the third row:
main.go:
package main
import (
"context"
"fmt"
"time"
"golang.org/x/sync/semaphore"
)
func main() {
oven := semaphore.NewWeighted(10)
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()
err := oven.Acquire(ctx, 12) // 12 kg can never fit in a 10 kg oven
fmt.Println("Acquire(12):", err)
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output:
$ go run .
Acquire(12): context deadline exceeded
And TryGo refusing when the group is full:
main.go:
package main
import (
"fmt"
"time"
"golang.org/x/sync/errgroup"
)
func main() {
var g errgroup.Group
g.SetLimit(2)
for i := 1; i <= 4; i++ {
ok := g.TryGo(func() error { time.Sleep(50 * time.Millisecond); return nil })
fmt.Println("upload", i, "started:", ok)
}
fmt.Println("error:", g.Wait())
}
go.mod:
module shop
go 1.24
require golang.org/x/sync v0.19.0
Commands:
$ go run .
Real output:
$ go run .
upload 1 started: true
upload 2 started: true
upload 3 started: false
upload 4 started: false
error: <nil>
Practice
- Change the home page so offers is optional: if it fails, show the page without offers, but if the menu fails, fail the page.
- Rewrite the
SetLimitdemo withsemaphore.NewWeighted(3)andAcquire(ctx, 1). - With
rate.NewLimiter(2, 1), at what times are 5 messages sent? - Add an
Unsubscribe(ch)method to the broker.
Solutions
1. Don't return the offers error from its task; log it and leave offers empty, but return the menu error:
g.Go(func() (err error) { menu, err = fetch("menu", 30*time.Millisecond, false); return })
g.Go(func() error {
var err error
if offers, err = fetch("offers", 10*time.Millisecond, true); err != nil {
fmt.Println("offers skipped:", err) // optional section
}
return nil
})
2. sem := semaphore.NewWeighted(3), and in each goroutine if err := sem.Acquire(ctx, 1); err != nil { return } followed by defer sem.Release(1). "most uploads at once" is still 3.
3. The bucket holds 1 token and starts full: message 1 at 0 ms, then one every 500 ms: 500, 1000, 1500, 2000 ms.
4.
func (b *Broker) Unsubscribe(c <-chan string) {
b.mu.Lock()
defer b.mu.Unlock()
for i, ch := range b.subs {
if ch == c {
close(ch)
b.subs = append(b.subs[:i], b.subs[i+1:]...)
return
}
}
}
(A receive-only <-chan string and a bidirectional chan string made by the same make compare equal.)
Quick quiz
1. lim := rate.NewLimiter(2, 4), then ten lim.Wait(ctx) calls in a row. How many messages go out at time 0? (From the video.)
A. 2 · B. 4 · C. 10 · D. 1
Answer
B. The bucket starts full with 4 tokens (the burst); after that, 2 a second.
2. With errgroup.WithContext, when is the context cancelled?
Answer
The first time a task returns a non-nil error, or when Wait returns, whichever comes first.
3. 100 goroutines call sf.Do("price", fn) at the same moment, and fn takes 50 ms. How many times does fn run?
Answer
Once. The other 99 callers wait for it and get the same result, with shared == true.
4. What does a buffered channel with a select/default send give you, compared with a slice that grows?
Answer
A bound on the queue: when it's full, the work is refused at once (load shedding) instead of piling up; without default, the send blocks (backpressure).
Interview questions
- How do you collect errors from many goroutines?
errgroup.Group:g.Go(func() error), theng.Wait()returns the first error. - What does
errgroup.WithContextadd? A context cancelled on the first error, so the other tasks can stop early (they must checkctx). - How do you limit concurrency with errgroup?
g.SetLimit(n);g.Goblocks whilentasks are active,g.TryGoreturns false instead. - When would you use
semaphore.Weighted? When tasks need different amounts of a shared resource (memory, connections, CPU slots). - What is a cache stampede and how does singleflight help? Many requests missing the cache at once hit the slow source together;
singleflight.Doruns one call per key and shares its result. - Explain a token bucket. A bucket of size b refilled at r tokens per second; each event takes a token; bursts up to b, average rate r.
- Rate limit vs concurrency limit? Rate limits how often things start (events/second); a concurrency limit caps how many run at the same moment.
- What is backpressure? A slow consumer slowing down a fast producer, e.g. a bounded channel whose send blocks when full.
- How do you implement pub/sub with channels? A broker with one channel per subscriber; publish sends a copy to each, and a slow subscriber is handled with a buffer and
select/default(drop) or a timeout. - How do you shut down a Go service gracefully?
signal.NotifyContextfor SIGINT/SIGTERM, stop accepting work, finish in-flight work with a deadline, clean up, exit; for HTTP,http.Server.Shutdown(ctx).
Glossary
| Term | Meaning | Example |
|---|---|---|
| Standard library | the packages that come with Go | fmt, sync, time |
golang.org/x |
extra packages by the Go team, downloaded separately | golang.org/x/sync |
| Module | a versioned collection of packages with a go.mod |
module shop |
go get |
adds or updates a module dependency | go get golang.org/x/sync@v0.19.0 |
require |
a go.mod line naming a needed module and version |
require golang.org/x/sync v0.19.0 |
go run . |
build and run the package in the current folder | in the video's package programs |
| Service | a separate program your app asks for data over the network | the offers service |
errgroup.Group |
a WaitGroup for tasks that return errors | g.Go(f), g.Wait() |
| First error | the first non-nil error any task returned; what Wait returns |
offers service is down |
errgroup.WithContext |
a group plus a context cancelled on the first error | g, ctx := errgroup.WithContext(bg) |
| Fail fast | stop all work as soon as one part fails | gave up after 10ms |
SetLimit |
at most n active goroutines in a group | g.SetLimit(3) |
TryGo |
start a task only if there's room now | ok := g.TryGo(f) |
| Weighted semaphore | a semaphore where each task takes a different amount | semaphore.NewWeighted(10) |
| Weight | the amount a task takes from a weighted semaphore | 6 kg for a biryani |
Acquire / Release |
take / give back n units | Acquire(ctx, 6), Release(6) |
TryAcquire |
take n units only if free now | TryAcquire(11) → false |
| FIFO | first in, first out: served in arrival order | the chicken before the paneer |
| Starvation | a task that's ready but never gets the resource | small orders always overtaking a big one |
| Cache | a fast store of recent answers | the price, kept for a minute |
| Expire | a cache entry stops being valid after a time | after one minute |
| Thundering herd / cache stampede | many requests hitting a slow source at once | 100 database calls |
singleflight.Group |
duplicate call suppression: one call per key at a time | sf.Do("thali-price", fn) |
| Key | the name of the question in Do |
"thali-price" |
shared |
whether a result went to more than one caller | true |
| Rate limiting | controlling how many events happen per unit of time | 5 SMS per second |
| HTTP 429 | the status "Too Many Requests" | sms 6: 429 Too Many Requests |
| Ticker | a channel that receives a value every interval | time.NewTicker(200*time.Millisecond) |
| Burst | how many events may happen at once | 3 |
| Token bucket | a bucket of tokens refilled at a rate; each event takes one | rate.NewLimiter(5, 3) |
rate.Limit |
events per second | 5 |
Wait / Allow / Reserve |
take a token: block / don't block / book a future one | lim.Wait(ctx) |
| Concurrency limit | how many run at the same moment | 3 uploads |
| Producer / consumer | the code that makes work / does it | the app / the cook |
| Unbounded queue | a queue with no size limit | queue = append(queue, i) |
| Bound | a maximum size | capacity 10 |
| Backpressure | the slow part pushing back on the fast part | a send blocking on a full channel |
| Load shedding | refusing extra work on purpose | "kitchen busy, try in a minute" |
| Pub/sub | publishers send, every subscriber gets a copy | staff announcements |
| Publisher / subscriber | sender / receiver of messages | the manager / the waiter |
| Broker | the middle part that keeps subscribers and delivers | Broker |
| Signal | a short message from the operating system to a program | SIGINT |
| SIGINT | the interrupt signal, sent by Ctrl+C | os.Interrupt |
| SIGTERM | the polite stop request; kill's default |
syscall.SIGTERM |
| SIGKILL / SIGSTOP | signals that can never be caught | kill -9 |
signal.NotifyContext |
a context cancelled when a signal arrives (Go 1.16) | ctx, stop := signal.NotifyContext(...) |
| Graceful shutdown | stop new work, finish, clean up, exit | kitchen closed cleanly |
Summary
errgroup.Group:g.Go(func() error),g.Wait()returns the first error.WithContextcancels the rest on that error (tasks must checkctx);SetLimit(n)caps active goroutines;TryGonever waits.semaphore.NewWeighted(n):Acquire(ctx, w)/Release(w)/TryAcquire(w)for tasks of different sizes; waiters are served in order.singleflight.Group.Do(key, fn): one call per key at a time, shared with everyone waiting: the cure for a cache stampede.- Rate limits:
time.Tickerfor a steady pace;rate.NewLimiter(r, burst)for a token bucket; preferWait, useAllowto drop. - Bound every queue: a full channel gives backpressure;
select+defaultgives load shedding. - Pub/sub: a broker with one channel per subscriber.
- Graceful shutdown:
signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM), checkctx.Done()between units of work, clean up, exit.
Next episode: concurrency bugs and testing concurrent code: goroutine leaks, deadlock, livelock, starvation, unbounded goroutines, forgotten cancels, goleak, testing/synctest and fake time, stress testing with -count and -race, and choosing between a mutex and a channel.