Runnable Go Docs: Mutex

Q: What is a mutex in Go?

A sync.Mutex is a lock that lets only one goroutine at a time run the code between mu.Lock() and mu.Unlock(). You use it to protect data that several goroutines read and write, such as a map or a struct. Its zero value is an unlocked mutex, ready to use.

Q: Is sync.Mutex reentrant in Go?

No. If a goroutine that holds the lock calls Lock again, it blocks forever waiting for itself. Structure the code so that exported methods take the lock and call unexported helpers that assume it is already held.

Protecting shared data

A sync.Mutex allows one goroutine at a time into the code between Lock and Unlock. Put the mutex next to the data it guards, usually in the same struct:

package main

import (
	"fmt"
	"sync"
)

type Counter struct {
	mu     sync.Mutex
	counts map[string]int
}

func (c *Counter) Inc(key string) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.counts[key]++
}

func (c *Counter) Get(key string) int {
	c.mu.Lock()
	defer c.mu.Unlock()
	return c.counts[key]
}

func main() {
	c := Counter{counts: make(map[string]int)}

	var wg sync.WaitGroup
	for range 100 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for range 100 {
				c.Inc("hits")
			}
		}()
	}
	wg.Wait()

	fmt.Println("hits:", c.Get("hits"))
}

This always prints hits: 10000. Without the lock, 100 goroutines writing the same map would usually crash the program with fatal error: concurrent map writes. That error comes from a best-effort check in the runtime, it cannot be recovered, and the lack of a crash does not prove the code is correct.

Details that matter:

The zero value of sync.Mutex is unlocked and ready. No constructor.
Methods use a pointer receiver (*Counter). A value receiver would lock a copy of the mutex, which protects nothing.
defer c.mu.Unlock() right after Lock means every return path, and a panic, releases the lock.
Every access goes through the lock, reads included. A read without the lock while another goroutine writes is still a data race.

Keep the critical section small

defer unlocks at the end of the function. That is right for short methods like the ones above. In a longer function, unlock as soon as the shared data is no longer touched, so other goroutines are not waiting on work that does not need the lock:

func (s *Store) Save(key string) error {
	s.mu.Lock()
	data := s.items[key] // copy what you need
	s.mu.Unlock()

	return writeToDisk(key, data) // slow I/O, outside the lock
}

Holding a lock across network calls, disk I/O or a channel send is the most common cause of a slow concurrent program, and a channel send under a lock is a common cause of deadlock.

RWMutex for read-heavy data

sync.RWMutex has two modes. RLock/RUnlock take a shared read lock that many goroutines can hold at once. Lock/Unlock take the exclusive write lock, which waits until all readers leave.

package main

import (
	"fmt"
	"sync"
)

type Config struct {
	mu     sync.RWMutex
	values map[string]string
}

func (c *Config) Get(key string) (string, bool) {
	c.mu.RLock()
	defer c.mu.RUnlock()
	v, ok := c.values[key]
	return v, ok
}

func (c *Config) Set(key, value string) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.values[key] = value
}

func main() {
	cfg := &Config{values: map[string]string{"mode": "dev"}}

	var wg sync.WaitGroup
	for range 50 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			cfg.Get("mode") // many readers at the same time
		}()
	}
	wg.Add(1)
	go func() {
		defer wg.Done()
		cfg.Set("mode", "prod") // one writer, exclusive
	}()
	wg.Wait()

	v, _ := cfg.Get("mode")
	fmt.Println("mode:", v)
}

RWMutex pays off when reads dominate and each read does real work under the lock. For tiny critical sections like a single map lookup, a plain Mutex is often just as fast, because the read lock has its own bookkeeping. Benchmark before choosing.

You cannot upgrade a read lock to a write lock. Calling Lock while holding RLock in the same goroutine deadlocks. Release the read lock first, then take the write lock and check the condition again, since another writer may have changed the data in between.

sync/atomic for single values

For one counter or flag, sync/atomic is simpler and cheaper than a mutex. The typed wrappers (Go 1.19) are the ones to use:

package main

import (
	"fmt"
	"sync"
	"sync/atomic"
)

func main() {
	var requests atomic.Int64
	var ready atomic.Bool

	var wg sync.WaitGroup
	for range 1000 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			requests.Add(1)
		}()
	}
	wg.Wait()
	ready.Store(true)

	fmt.Println("requests:", requests.Load())
	fmt.Println("ready:", ready.Load())

	// CompareAndSwap: set only if the current value is what you expect.
	fmt.Println("swapped:", requests.CompareAndSwap(1000, 0), "now:", requests.Load())
}

Atomics protect one value at a time. As soon as two values must change together (a balance and a transaction count, a map and its size), use a mutex. Two separate atomic operations can interleave with other goroutines between them.

sync.Once

sync.Once runs a function exactly once, no matter how many goroutines call it at the same time. Everyone who calls Do waits until the first call has finished. It is the standard way to initialize something lazily:

package main

import (
	"fmt"
	"sync"
)

var (
	once   sync.Once
	config map[string]string
)

func loadConfig() map[string]string {
	once.Do(func() {
		fmt.Println("loading config (runs once)")
		config = map[string]string{"env": "prod"}
	})
	return config
}

// Go 1.21: OnceValue wraps a function and caches its result.
var port = sync.OnceValue(func() int {
	fmt.Println("computing port (runs once)")
	return 8080
})

func main() {
	var wg sync.WaitGroup
	for range 5 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			_ = loadConfig()
			_ = port()
		}()
	}
	wg.Wait()
	fmt.Println(loadConfig()["env"], port())
}

Each "runs once" line appears exactly once. If the function passed to Do panics, Once still counts it as done and never retries. sync.OnceValues does the same for functions that return two values, typically a value and an error.

Mutex, channel, or sync.Map

Situation	Use
A struct or map that several goroutines update in place	`sync.Mutex` in the struct
Mostly reads, occasional writes, reads do real work	`sync.RWMutex`
A single counter or flag	`sync/atomic`
One-time initialization	`sync.Once`, `sync.OnceValue`
Handing data from one goroutine to another	a channel
A cache whose keys are written once and read many times, or goroutines touching disjoint keys	`sync.Map`

sync.Map is not a general replacement for a locked map. It has no type parameters, so values come back as any, and it is only faster in the two cases in the table. Start with a mutex and a normal map.

Common mistakes

Copying a mutex. Passing a struct that contains a sync.Mutex by value, or using a value receiver, copies the lock. go vet reports passes lock by value or copies lock value.
Locking twice in one goroutine. Go mutexes are not reentrant. If Inc calls Get and both take the lock, Inc blocks forever. Have public methods lock, and private helpers assume the lock is held.
Forgetting to unlock on an early return. Use defer unless you have a reason not to.
Locking in different orders. If one goroutine takes lock A then B while another takes B then A, both can wait on each other forever. Always acquire multiple locks in the same order.
Exposing the guarded data. Returning the internal map from a method lets callers read and write it without the lock. Return a copy (maps.Clone, Go 1.21) or a single value.
Protecting only the writes. Unlocked reads concurrent with locked writes are still races. Run your tests with go test -race.

Frequently Asked Questions

What is a mutex in Go?

A sync.Mutex is a lock that lets only one goroutine at a time run the code between mu.Lock() and mu.Unlock(). You use it to protect data that several goroutines read and write, such as a map or a struct. Its zero value is an unlocked mutex, ready to use.

When should I use RWMutex instead of Mutex?

When reads greatly outnumber writes and each read holds the lock for a meaningful amount of time. RLock lets any number of readers in at once, while Lock waits for exclusive access. For short critical sections a plain Mutex is often as fast or faster, so measure before switching.

Is a Go map safe for concurrent use?

No. Concurrent reads are fine, but a write concurrent with any other read or write is a data race, and the runtime usually detects it and crashes with fatal error: concurrent map writes (or concurrent map read and map write). Protect the map with a sync.Mutex or sync.RWMutex, or use sync.Map for its specific use cases.

Is sync.Mutex reentrant in Go?

No. If a goroutine that holds the lock calls Lock again, it blocks forever waiting for itself. Structure the code so that exported methods take the lock and call unexported helpers that assume it is already held.

Related concepts