What happens when a method holding a sync.Mutex calls another method that locks the same mutex?

## The mechanism A `sync.Mutex` is a tiny struct holding a state word and a semaphore. The state word says *locked* or *not locked*; it does not say *locked by goroutine G*. There is no owner field, no recursion counter, and no bookkeeping that could tell one goroutine's second `Lock` apart from a different goroutine's first one. So this happens: ```go func (s *Scoreboard) RecordWin() { s.mu.Lock() defer s.mu.Unlock() s.wins++ } func (s *Scoreboard) RecordSweep(n int) { s.mu.Lock() defer s.mu.Unlock() for i := 0; i < n; i++ { s.RecordWin() // parks here, forever } } ``` `RecordSweep` takes the lock. `RecordWin` asks for the same lock. The mutex is held, so the runtime parks the goroutine on the mutex's wait queue. The only code that could release it is the deferred `Unlock` in `RecordSweep` - which cannot run, because `RecordSweep` is blocked inside `RecordWin`. The goroutine waits on itself. The damage is not limited to that one goroutine. The mutex stays held, so every other goroutine that touches the scoreboard queues behind it. A single self-deadlock in a shared object usually looks, from the outside, like the whole feature has stopped: requests pile up, the queue depth climbs, and the process is otherwise healthy. ## Why Go does not give you a recursive mutex This is a design choice, not an oversight. A lock exists to protect an *invariant*: while it is held, the guarded fields may be temporarily inconsistent. A recursive lock lets a function re-enter a critical section that some outer frame has already half-finished, and see exactly that inconsistent state while believing it holds the lock legitimately. Go's answer is to make the impossible case loud - it deadlocks immediately and reproducibly - rather than quietly correct-looking. It is also why the mutex has no owner in the first place: without ownership there is no way to make it recursive, and without recursion there is no need to track ownership. That same absence is what makes it legal for one goroutine to lock a mutex and another to unlock it. ## The idiom that prevents it Go codebases converge on one convention. Split every operation into two functions: ```go // recordWinLocked assumes s.mu is already held. func (s *Scoreboard) recordWinLocked() { s.wins++ } func (s *Scoreboard) RecordWin() { s.mu.Lock() defer s.mu.Unlock() s.recordWinLocked() } ``` The rules that fall out of it: 1. **A method either locks or assumes the lock, never both.** The exported one locks; the unexported one assumes. 2. **Name the assumption.** The `Locked` suffix (or a prefix like `unsafeXxx`, or simply a comment) is the only documentation the compiler will not give you. Write it on every such helper. 3. **Locking methods call only non-locking ones.** Once a critical section calls another exported method, the invariant is broken and the deadlock is a matter of time. 4. **Never call foreign code while holding the mutex.** A callback field, an interface value, a `fmt.Stringer` on a caller's type, a `log` handler somebody swapped out - any of these can call back into your package and re-enter. Gather what you need under the lock, unlock, then call out. ## Recognising it in the wild The symptom is a goroutine that is parked and never comes back, with a stack that shows two frames of *your own type* between `sync.(*Mutex).Lock` and the entry point - the outer method and the inner one. That shape, one type appearing twice in the same stack around a lock, is the tell. Because the mutex records no owner, nothing in the runtime can say *who* holds it; you infer the holder from the stacks of the other goroutines. That is why the naming convention matters so much: the code has to be reviewable, since the runtime will not explain it for you. ## Bad fixes to avoid - **Unlocking before the nested call and relocking after.** This does stop the hang, and it silently breaks atomicity: the guarded fields are exposed, mid-update, to every other goroutine in the gap. - **A hand-rolled recursion counter.** To make it correct you would need to know which goroutine holds the lock, and Go deliberately gives you no goroutine identity to key that on. - **Swapping in `TryLock` on the inner call.** It stops the block, but the inner method then either skips its work or proceeds without the guarantee it was written to assume. The honest fix is always structural: one lock acquisition per operation, at the outermost layer, with everything below it written to run under a lock it did not take.