sync.Mutex

## What a sync.Mutex is A `sync.Mutex` is Go's basic mutual-exclusion lock: at most one goroutine may hold it at a time. It exists so that several goroutines can touch the same variables without their reads and writes overlapping - which in Go is not merely untidy but a data race, undefined behaviour that the compiler and runtime are free to turn into corrupted values or crashes. The type has exactly two methods you use day to day: `Lock`, which blocks the calling goroutine until the mutex is available and then takes it, and `Unlock`, which releases it. Neither returns anything. ## Why there is no constructor Go's standard library leans hard on the idea of a *usable zero value*: a type whose all-zero form is already meaningful. `sync.Mutex`'s zero value is an unlocked mutex, so all of these are correct and complete: ```go var mu sync.Mutex // package-level or local type Scoreboard struct { mu sync.Mutex // ready as soon as a Scoreboard exists wins int } board := &Scoreboard{} // nothing else to initialise ``` There is deliberately no `sync.NewMutex`. If you ever see one in a codebase, it is somebody's own wrapper. This matters more than it sounds: because the zero value works, a struct that embeds a mutex needs no constructor of its own, and a forgotten initialisation cannot silently produce a lock that does not lock. The other half of that bargain is the rule from the package docs: **a `Mutex` must not be copied after first use.** Because it is a plain struct, assigning it or passing it by value copies it, and the copy is a *different* lock. That is why lock-bearing types are used through pointers and their methods take pointer receivers. ## The Lock / defer Unlock pattern The idiom is two adjacent lines: ```go func (s *Scoreboard) RecordWin() { s.mu.Lock() defer s.mu.Unlock() s.wins++ } ``` Why `defer` rather than a plain `s.mu.Unlock()` at the end? - **Every return path is covered.** A function that grows a second `return` later cannot forget one. - **A panic still releases the lock.** Deferred calls run while the goroutine unwinds, so a panic in the middle of the critical section does not leave the mutex held forever - every other goroutine would otherwise block on it for the life of the process. - **It is reviewable.** `Lock` and `defer Unlock` on consecutive lines is a pattern a reader recognises instantly; a lone `Lock` with the matching `Unlock` forty lines away is where bugs live. ## Where the mutex lives Convention is a small unexported field placed immediately above the data it protects, with a comment that says what it guards: ```go type Scoreboard struct { mu sync.Mutex // guards wins and losses wins int losses int } ``` Keep the field unexported so callers outside the package cannot lock or unlock it; the type's methods are the only thing that should. For the same reason, avoid *embedding* `sync.Mutex` anonymously in an exported struct - embedding promotes `Lock` and `Unlock` into the type's public API, which you then have to support forever and which invites callers to take the lock for you. ## Things worth knowing early - **`Lock` cannot fail and cannot time out.** There is no error return and no deadline parameter. If the mutex is held, your goroutine waits. - **Unlocking an unlocked mutex is fatal.** The program dies with `fatal error: sync: unlock of unlocked mutex`; `recover` does not catch it, because it is a runtime fatal error rather than an ordinary panic. - **A `sync.Mutex` has no owner.** It records nothing about which goroutine locked it, so it is legal (though unusual and hard to review) for one goroutine to lock it and another to unlock it. The absence of ownership is also why locking it twice from the same goroutine deadlocks rather than being detected. - **The mutex protects nothing by itself.** The compiler will not stop you reading `s.wins` without taking `s.mu`; the guarantee comes entirely from every access agreeing to take the lock. That agreement is what the comment above the field is documenting. - **Run the race detector.** `go test -race` is what catches an access path that forgot the lock; a clean build proves nothing about it. ## A minimal mental model Declare it, never copy it, lock it, defer the unlock, touch the guarded fields, return. Everything else about `sync.Mutex` - non-reentrancy, `TryLock`, contention - is a refinement of those five steps.