sync.Cond

## What `sync.Cond` is `sync.Cond` is Go's condition variable: a place for goroutines to park until some shared, lock-protected state changes. It does not carry data and it does not do any locking on its own — it is always paired with a lock that protects the state the goroutines care about. The whole type is three methods and one field: - `func sync.NewCond(l sync.Locker) *sync.Cond` - `func (c *sync.Cond) Wait()` - `func (c *sync.Cond) Signal()` - `func (c *sync.Cond) Broadcast()` - the field `c.L sync.Locker` `sync.Locker` is just the interface `{ Lock(); Unlock() }`, so a `*sync.Mutex` qualifies, and so does a `*sync.RWMutex` (or the read-only `Locker` its `RLocker` method returns). In practice you pass the mutex that already guards the data — that pairing is the point. ## Construction Unlike `sync.Mutex`, the zero `sync.Cond` is **not** ready to use, because its `L` field would be a nil `Locker` and the first `Wait` would dereference nil. Build it with `sync.NewCond`, typically right after the struct that owns it, and store the pointer: ``` q := &queue{} q.notEmpty = sync.NewCond(&q.mu) ``` Always pass and store `*sync.Cond`, never a `sync.Cond` value: the type contains a copy checker, and using a copy made after first use panics with `sync.Cond is copied`. ## The `Wait` contract, which is the part interviews test Three things happen in `Wait`, in this order: 1. It **unlocks `c.L`**. This is why you must already hold `c.L` when you call it — `Wait` starts by calling `c.L.Unlock()`. Calling it without the lock held is not a friendly error: with a `*sync.Mutex` you get `fatal error: sync: unlock of unlocked mutex`, which is a runtime fatal error that `recover` cannot catch and that takes the whole process down. 2. It **parks the goroutine** on the condition's internal notify list. The release and the park are atomic with respect to `Signal`/`Broadcast`, so a wake-up that happens "just after" you released the lock is not lost. 3. When woken, it **re-acquires `c.L`** and only then returns. So on the statement after `c.Wait()` you are holding the lock again, exactly as you were before the call, and a `defer c.L.Unlock()` at the top of the function is still correct. The important consequence is the middle step: while you are parked, you hold nothing. Other goroutines take the lock and mutate the state freely. So the fact that you were woken tells you only that somebody called `Signal` or `Broadcast` — it does not tell you that the thing you are waiting for is still true when you get the lock back. Another goroutine may have woken first and consumed the item. That is why the shared state, not the wake-up, is the source of truth: you re-read it after `Wait` returns. Go's documentation adds a guarantee that not every condition-variable implementation makes: `Wait` cannot return unless it was woken by `Broadcast` or `Signal`. There are no spurious wakeups in Go. The re-check is still needed, but for the lock-gap reason above rather than for random wakeups. ## A worked shape An embedded message broker holding a bounded in-memory queue is the classic fit: consumers block until there is something to take. ``` func (q *queue) take() string { q.mu.Lock() defer q.mu.Unlock() for len(q.items) == 0 { q.notEmpty.Wait() } v := q.items[0] q.items = q.items[1:] return v } ``` Every mutation of `q.items` elsewhere happens under `q.mu` and is followed by a `Signal` or `Broadcast` on `q.notEmpty`. The consumer never touches the condition variable except through this shape. ## What goes wrong - Calling `Wait` without holding `c.L` — fatal error, process dies. - A `sync.Cond` declared as a value and copied into a method receiver or a channel — `sync.Cond is copied` panic. - Building a `Cond` over one lock while guarding the state with a different one — the release-and-repark window is then unprotected and the state can change without any waiter being woken. - Treating `Wait` as a sleep. It is not timed; nothing but `Signal` or `Broadcast` on that same `Cond` will bring the goroutine back, which is why a parked waiter shows up in a goroutine dump sitting in `sync.(*Cond).Wait` and stays there.