- Waiting for Goroutines with a WaitGroup
- Error Management with Error Groups
- Data Races
- Synchronizing Access with a Mutex
- Performing Tasks Only Once
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Synchronizing Access with a Mutex
When you run tests with the -race flag, Go’s built-in race detector can help you find data races in your code. In Listing 13.30, for example, tests that pass normally fail when run with the race detector. The failure message lists the data race found and where the reads and writes occur in our code.
Listing 13.30 Detecting Race Conditions in Tests
$ go test -v -race
=== RUN Test_Mutex
=== PAUSE Test_Mutex
=== CONT Test_Mutex
--- PASS: Test_Mutex (0.00s)
PASS
==================
WARNING: DATA RACE
Read at 0x00c00019e3f0 by goroutine 9:
runtime.mapdelete()
/usr/local/go/src/runtime/map.go:695 +0x46c
demo.Test_Mutex.func2()
./demo_test.go:46 +0x50
Previous write at 0x00c00019e3f0 by goroutine 8:
runtime.mapaccess2_fast64()
/usr/local/go/src/runtime/map_fast64.go:53 +0x1cc
demo.Test_Mutex.func1()
./demo_test.go:32 +0x50
Goroutine 9 (running) created at:
demo.Test_Mutex()
./demo_test.go:43 +0x188
testing.tRunner()
/usr/local/go/src/testing/testing.go:1439 +0x18c
testing.(*T).Run.func1()
/usr/local/go/src/testing/testing.go:1486 +0x44
Goroutine 8 (finished) created at:
demo.Test_Mutex()
./demo_test.go:28 +0x124
testing.tRunner()
/usr/local/go/src/testing/testing.go:1439 +0x18c
testing.(*T).Run.func1()
/usr/local/go/src/testing/testing.go:1486 +0x44
==================
0: true
2: true
4: true
7: true
9: true
1: true
3: true
5: true
6: true
8: true
Found 1 data race(s)
exit status 66
FAIL demo 0.862s
Go Version: go1.19
In the test in Listing 13.31, we have two different goroutines. The first is modifying a shared resource—in this case, a map. The second goroutine is ranging over the map and printing out the map’s values.
In order for us to be able to fix this race condition, we need to be able to synchronize access to the shared resource.
Listing 13.31 Two Goroutines Accessing a Shared Map
// launch a goroutine to
// read data from the map
go func() {
// loop through the map
// and print the keys/values
for k, v := range data {
fmt.Printf("%d: %v\n", k, v)
}
}()
// launch a goroutine to
// put data in the map
go func() {
for i := 0; i < 10; i++ {
// loop putting data in the map
data[i] = true
}
// cancel the context
cancel()
}()
Locker
To synchronize access to the shared resource, we need to be able to lock access to the resource. By locking a shared resource, we can ensure that only one goroutine at a time can access the resource and that the resource is not modified by another goroutine while it is locked.
The sync.Locker16 interface, Listing 13.32, defines the methods that a type must implement to be able to lock and unlock a shared resource.
Listing 13.32 The sync.Locker Interface
$ go doc sync.Locker
package sync // import "sync"
type Locker interface {
Lock()
Unlock()
}
A Locker represents an object that can be locked and unlocked.
Go Version: go1.19
Locker Methods
You can use the sync.Locker.Lock17 method, Listing 13.33, to lock the shared resource. Once a resource is locked, no other goroutine can access the resource until it is unlocked.
Listing 13.33 The sync.Locker.Lock Method
$ go doc sync.Mutex.Lock
package sync // import "sync"
func (m *Mutex) Lock()
Lock locks m. If the lock is already in use, the calling goroutine blocks
until the mutex is available.
Go Version: go1.19
You can use the sync.Locker.Unlock18 method, Listing 13.34, to unlock the shared resource. Once a resource is unlocked, other goroutines can access the resource.
Listing 13.34 The sync.Locker.Unlock Method
$ go doc sync.Mutex.Unlock
package sync // import "sync"
func (m *Mutex) Unlock()
Unlock unlocks m. It is a run-time error if m is not locked on entry to
Unlock.
A locked Mutex is not associated with a particular goroutine. It is
allowed for one goroutine to lock a Mutex and then arrange for another
goroutine to unlock it.
Go Version: go1.19
Using a Mutex
The most basic mutex available in Go is the sync.Mutex type, Listing 13.35. The sync.Mutex uses a basic binary semaphore lock. This means that only one goroutine can access the resource at a time.
Listing 13.35 The sync.Mutex Type
$ go doc sync.Mutex
package sync // import "sync"
type Mutex struct {
// Has unexported fields.
}
A Mutex is a mutual exclusion lock. The zero value for a Mutex is an
unlocked mutex.
A Mutex must not be copied after first use.
func (m *Mutex) Lock()
func (m *Mutex) TryLock() bool
func (m *Mutex) Unlock()
Go Version: go1.19
To use a sync.Mutex, you need to wrap the areas of code that you want to synchronize access to by first locking the sync.Mutex and then unlocking it. For example, in the second goroutine in Listing 13.36, a mutex is being used to lock access around writing values into the data map.
Listing 13.36 Locking Resources with a sync.Mutex
// launch a goroutine to
// read data from the map
go func() {
// lock the mutex
mu.Lock()
// loop through the map
// and print the keys/values
for k, v := range data {
fmt.Printf("%d: %v\n", k, v)
}
// unlock the mutex
mu.Unlock()
}()
// launch a goroutine to
// put data in the map
go func() {
for i := 0; i < 10; i++ {
// lock the mutex
mu.Lock()
// loop putting data in the map
data[i] = true
// unlock the mutex
mu.Unlock()
}
// cancel the context
cancel()
}()
By locking access to the shared resource, you can ensure that only one goroutine at a time can access the resource. Our test output, Listing 13.37, confirms that the shared resource is only accessed by one goroutine at a time with a successful exit.
Listing 13.37 Passing Race Detector Tests
$ go test -v -race === RUN Test_Mutex === PAUSE Test_Mutex === CONT Test_Mutex 9: true --- PASS: Test_Mutex (0.00s) 0: true 2: true 5: true 8: true 7: true 1: true PASS 3: true 4: true 6: true ok demo 0.810s
Go Version: go1.19
RWMutex
Often, applications read a shared resource instead of writing to them. The sync.Mutex is a very heavy-weight locking mechanism. Access to a shared resource, whether it be a read or write, is blocked until the resource is unlocked. Only one goroutine can access a shared resource at a time.
When you want to be able to both read and write to a shared resource, you need to use a sync.RWMutex, Listing 13.38. The sync.RWMutex is a lighter-weight locking mechanism. A sync.RWMutex can allow many goroutines to read from the resource at the same time, but only one goroutine can write to the resource at a time.
Listing 13.38 The sync.RWMutex Type
$ go doc sync.RWMutex
package sync // import "sync"
type RWMutex struct {
// Has unexported fields.
}
A RWMutex is a reader/writer mutual exclusion lock. The lock can be held
by an arbitrary number of readers or a single writer. The zero value for
a RWMutex is an unlocked mutex.
A RWMutex must not be copied after first use.
If a goroutine holds a RWMutex for reading and another goroutine might
call Lock, no goroutine should expect to be able to acquire a read lock
until the initial read lock is released. In particular, this prohibits
recursive read locking. This is to ensure that the lock eventually
becomes available; a blocked Lock call excludes new readers from
acquiring the lock.
func (rw *RWMutex) Lock()
func (rw *RWMutex) RLock()
func (rw *RWMutex) RLocker() Locker
func (rw *RWMutex) RUnlock()
func (rw *RWMutex) TryLock() bool
func (rw *RWMutex) TryRLock() bool
func (rw *RWMutex) Unlock()
Go Version: go1.19
The sync.RWMutex offers two additional methods beyond those of the sync.Locker interface. You can use the sync.RWMutex.Rlock19 and sync.RWMutex.RUnlock20 methods to lock the resource for reading. The sync.RWMutex.Lock21 and sync.RWMutex.Unlock22 methods are used to lock the resource across all goroutines for writing.
In Listing 13.39, we update the goroutine that is reading the resource to use the sync.RWMutex.Rlock method instead of the sync.Mutex.Lock method. This will allow for many goroutines to read from the resource at the same time.
Listing 13.39 Using a sync.RWMutex
// launch a goroutine to
// read data from the map
go func() {
// lock the mutex
mu.RLock()
// loop through the map
// and print the keys/values
for k, v := range data {
fmt.Printf("%d: %v\n", k, v)
}
// unlock the mutex
mu.RUnlock()
}()
$ go test -v -race === RUN Test_RWMutex === PAUSE Test_RWMutex === CONT Test_RWMutex 4: true 5: true 6: true --- PASS: Test_RWMutex (0.00s) 7: true 9: true 0: true 1: true PASS 8: true 2: true 3: true ok demo 0.917s
Go Version: go1.19
The tests in Listing 13.39 continue to pass, but the performance of the program is improved by allowing multiple goroutines to read from the shared resource instead of arbitrarily locking all goroutines all at once.
Improper Usage
When using either sync.Mutex or sync.RWMutex, you must take care in making sure to lock and unlock in the proper order.
Consider Listing 13.40. We have a sync.Mutex, and we attempt to call sync.Mutex.Lock twice.
Listing 13.40 Attempting to Lock a sync.Mutex Twice
func Test_Mutex_Locks(t *testing.T) {
t.Parallel()
// create a new mutex
var mu sync.Mutex
// lock the mutex
mu.Lock()
fmt.Println("locked. locking again.")
// try to lock the mutex again
// this will block/deadlock
// because the mutex is already locked
// and the lock was not released
mu.Lock()
fmt.Println("unlocked twice")
}
The result is the program will deadlock and crash, as shown in Listing 13.41. The reason is that a call to sync.Mutex.Lock blocks until the sync.Mutex.Unlock method is called. Because we have already locked the sync.Mutex, the second call to sync.Mutex.Lock blocks indefinitely because it is never unlocked.
Listing 13.41 A Panic while Trying to Unlock an Already-Unlocked sync.Mutex
$ go test -v -timeout 10ms
=== RUN Test_Mutex_Locks
=== PAUSE Test_Mutex_Locks
=== CONT Test_Mutex_Locks
locked. locking again.
panic: test timed out after 10ms
goroutine 33 [running]:
testing.(*M).startAlarm.func1()
/usr/local/go/src/testing/testing.go:2029 +0x8c
created by time.goFunc
/usr/local/go/src/time/sleep.go:176 +0x3c
goroutine 1 [chan receive]:
testing.tRunner.func1()
/usr/local/go/src/testing/testing.go:1405 +0x45c
testing.tRunner(0x140001361a0, 0x1400010fcb8)
/usr/local/go/src/testing/testing.go:1445 +0x14c
testing.runTests(0x1400001e1e0?, {0x100ec9ea0, 0x1, 0x1},
{0xe00000000000000?, 0x100cf5218?, 0x100ed2640?})
/usr/local/go/src/testing/testing.go:1837 +0x3f0
testing.(*M).Run(0x1400001e1e0)
/usr/local/go/src/testing/testing.go:1719 +0x500
main.main()
_testmain.go:47 +0x1d0
goroutine 4 [semacquire]:
sync.runtime_SemacquireMutex(0x1400000e018?, 0x20?, 0x17?)
/usr/local/go/src/runtime/sema.go:71 +0x28
sync.(*Mutex).lockSlow(0x14000012140)
/usr/local/go/src/sync/mutex.go:162 +0x180
sync.(*Mutex).Lock(...)
/usr/local/go/src/sync/mutex.go:81
demo.Test_Mutex_Locks(0x0?)
./demo_test.go:25 +0x130
testing.tRunner(0x14000136340, 0x100e25298)
/usr/local/go/src/testing/testing.go:1439 +0x110
created by testing.(*T).Run
/usr/local/go/src/testing/testing.go:1486 +0x300
exit status 2
FAIL demo 0.527s
Go Version: go1.19
Worse than a deadlock caused by waiting for a lock that will never be unlocked is unlocking a lock that has not been locked.
In Listing 13.42, the result is a fatal error that crashes the application. The reason is that we have not locked the sync.Mutex before attempting to unlock it.
Listing 13.42 A Panic while Trying to Unlock an Unlocked sync.Mutex
func Test_Mutex_Unlock(t *testing.T) {
t.Parallel()
// create a new mutex
var mu sync.Mutex
// unlock the mutex
mu.Unlock()
}
$ go test -v
=== RUN Test_Mutex_Unlock
=== PAUSE Test_Mutex_Unlock
=== CONT Test_Mutex_Unlock
fatal error: sync: unlock of unlocked mutex
goroutine 18 [running]:
runtime.throw(0x104573b02?, 0x1400005af18?)
/usr/local/go/src/runtime/panic.go:992 +0x50 fp=0x1400005aee0
sp=0x1400005aeb0 pc=0x1044ba9a0
sync.throw(0x104573b02?, 0x1045b6260?)
/usr/local/go/src/runtime/panic.go:978 +0x24 fp=0x1400005af00
sp=0x1400005aee0 pc=0x1044e5664
sync.(*Mutex).unlockSlow(0x140001280b0, 0xffffffff)
/usr/local/go/src/sync/mutex.go:220 +0x3c fp=0x1400005af30
sp=0x1400005af00 pc=0x1044ef44c
sync.(*Mutex).Unlock(...)
/usr/local/go/src/sync/mutex.go:214
demo.Test_Mutex_Unlock(0x0?)
./demo_test.go:16 +0x74 fp=0x1400005af60 sp=0x1400005af30
pc=0x10456d794
testing.tRunner(0x1400010b380, 0x1045c9298)
/usr/local/go/src/testing/testing.go:1439 +0x110 fp=0x1400005afb0
sp=0x1400005af60 pc=0x104537660
testing.(*T).Run.func1()
/usr/local/go/src/testing/testing.go:1486 +0x30 fp=0x1400005afd0
sp=0x1400005afb0 pc=0x1045383d0
runtime.goexit()
/usr/local/go/src/runtime/asm_arm64.s:1263 +0x4 fp=0x1400005afd0
sp=0x1400005afd0 pc=0x1044ea2a4
created by testing.(*T).Run
/usr/local/go/src/testing/testing.go:1486 +0x300
goroutine 1 [chan receive]:
testing.tRunner.func1()
/usr/local/go/src/testing/testing.go:1405 +0x45c
testing.tRunner(0x1400010b1e0, 0x14000131cb8)
/usr/local/go/src/testing/testing.go:1445 +0x14c
testing.runTests(0x140001421e0?, {0x10466dea0, 0x1, 0x1}, {0xa500000000000000?,
0x104499218?, 0x104676640?})
/usr/local/go/src/testing/testing.go:1837 +0x3f0
testing.(*M).Run(0x140001421e0)
/usr/local/go/src/testing/testing.go:1719 +0x500
main.main()
_testmain.go:47 +0x1d0
exit status 2
FAIL demo 0.260s
Go Version: go1.19
Wrapping Up Read/Write Mutexes
While there are pitfalls and areas of concern when using mutexes, such as deadlocks and improper usage, sync.Mutex and sync.RWMutex are excellent tools for protecting shared resources. They are also the most commonly used locking mechanisms in Go.