What does embedding `sync.Mutex` in an exported Go struct expose to that package's importers?

## An embedded lock is a published locking protocol `sync.Mutex` has three exported methods - `Lock`, `Unlock` and `TryLock`. Embedding it in a struct promotes all three onto that struct: ```go type Counter struct { sync.Mutex n int } ``` `Counter` now has `Lock`, `Unlock` and `TryLock` in its method set, exactly as if you had declared them. If `Counter` is exported, so are those methods, and every package that imports yours can call them. ### Why promotion crosses the package boundary The rule that trips people up is that **export is decided by the method's own name, not by the field's**. `sync.Mutex` is an exported type, so the embedded field is called `Mutex` and is itself exported - `c.Mutex` and `&c.Mutex` are reachable from another package, and your lock can be handed around as a `sync.Locker`. But even embedding an *unexported* type promotes its exported methods: an unexported `logger` embedded in an exported `Server` still gives importers `Server.Log`. Only methods whose own names begin with a lower-case letter stay inside the package. ### What that costs you **You have published a protocol you did not design.** A caller can now write: ```go c.Lock() somethingSlow() c.Unlock() ``` and hold your internal lock for as long as they like, across code you have never seen. They can also unlock a mutex they never locked, which panics, or lock twice - `sync.Mutex` is not reentrant, so that deadlocks. Every one of those failures shows up as your type misbehaving. **You have frozen the implementation.** Locking is the kind of decision you want to keep changing: coarse mutex first, then a read-write lock, then a sharded set of locks, then atomics for a hot counter. Once `Lock` and `Unlock` are exported methods, removing them is a breaking change to your module's API. Even a benign-looking swap to `sync.RWMutex` silently adds `RLock` and `RUnlock` to your exported surface, which you then also cannot withdraw. **You have widened interface satisfaction.** Your type now satisfies `sync.Locker` and anything else shaped like it. Code elsewhere can accept it in places you never intended. ### The alternative, and what it costs Keep the lock unexported and named, and expose operations rather than mechanism: ```go type SafeCounter struct { mu sync.Mutex n int } func (c *SafeCounter) Add(d int) { c.mu.Lock() defer c.mu.Unlock() c.n += d } ``` The cost is that you write a method for each operation. The benefit is that the *only* concurrency contract you publish is "these methods are safe to call from multiple goroutines" - which is what a doc comment should say - and you can implement that however you like forever. Types in the standard library that need internal locking hold it in an unexported field for exactly this reason. ### Two details worth knowing - **Copying.** A struct containing a mutex must not be copied after first use; copying duplicates the lock state and the two copies no longer exclude each other. The `copylocks` analyzer in `go vet` reports passing or assigning such a value, whether the lock is embedded or named. - **Zero value.** A `sync.Mutex` is usable at its zero value, so both forms work with no constructor. That convenience is often what tempts people into embedding: there is no initialisation to write either way, so embedding looks like it costs nothing. ### When embedding a lock is actually right Rarely, but it happens: a type whose entire purpose is to *be* a lock with a little extra state, where callers are expected to bracket their own critical sections. If that is genuinely the contract - and you would write and document `Lock` and `Unlock` by hand - embedding is honest. The test is that question: would you hand-write each promoted method and stand behind it in your API docs? If not, the method should not be there.