go-deadlock

> 编程语言

Open source

Online deadlock detection in go (golang)

1.2K stars0 likes0 views

Website GitHub

About

Online deadlock detection in go (golang)

Online deadlock detection in go (golang).

Why

Deadlocks happen and are painful to debug.

What

go-deadlock provides (RW)Mutex drop-in replacements for sync.(RW)Mutex. It would not work if you create a spaghetti of channels. Mutexes only.

Installation

bash

go get github.com/sasha-s/go-deadlock/...

Usage

import "github.com/sasha-s/go-deadlock"
var mu deadlock.Mutex
// Use normally, it works exactly like sync.Mutex does.
mu.Lock()

defer mu.Unlock()
// Or
var rw deadlock.RWMutex
rw.RLock()
defer rw.RUnlock()

Deadlocks

One of the most common sources of deadlocks is inconsistent lock ordering: say, you have two mutexes A and B, and in some goroutines you have

A.Lock() // defer A.Unlock() or similar.
...
B.Lock() // defer B.Unlock() or similar.

And in another goroutine the order of locks is reversed:

B.Lock() // defer B.Unlock() or similar.
...
A.Lock() // defer A.Unlock() or similar.

Another common sources of deadlocks is duplicate take a lock in a goroutine:

A.Rlock() or lock()

A.lock() or A.RLock()

This does not guarantee a deadlock (maybe the goroutines above can never be running at the same time), but it usually a design flaw at least.

go-deadlock can detect such cases (unless you cross goroutine boundary - say lock A, then spawn a goroutine, block until it is singals, and lock B inside of the goroutine), even if the deadlock itself happens very infrequently and is painful to reproduce!

Each time go-deadlock sees a lock attempt for lock B, it records the order A before B, for each lock that is currently being held in the same goroutine, and it prints (and exits the program by default) when it sees the locking order being violated.

In addition, if it sees that we are waiting on a lock for a long time (opts.DeadlockTimeout, 30 seconds by default), it reports a potential deadlock, also printing the stacktrace for a goroutine that is currently holding the lock we are desperately trying to grab.

Sample output

Inconsistent lock ordering:

…

go package main

import ( "fmt" "sync" )

func main() { var mu sync.RWMutex

chrlockTwice := make(chan struct{}) // Used to control rlockTwice
rlockTwice := func() {
	mu.RLock()
	fmt.Println("first Rlock succeeded")
	<-chrlockTwice
	<-chrlockTwice
	fmt.Println("trying to Rlock again")
	mu.RLock()
	fmt.Println("second Rlock succeeded")
	mu.RUnlock()
	mu.RUnlock()
}

chLock := make(chan struct{}) // Used to contol lock
lock := func() {
	<-chLock
	fmt.Println("about to Lock")
	mu.Lock()
	fmt.Println("Lock succeeded")
	mu.Unlock()
	<-chLock
}

control := func() {
	chrlockTwice <- struct{}{}
	chLock <- struct{}{}

	close(chrlockTwice)
	close(chLock)
}

go control()
go lock()
rlockTwice()

}

…

bash

Normal development/testing

go test ./...

Testing with synctest (Go 1.25+, recommended)

GODEBUG=asynctimerchan=0 go test -tags=deadlock_synctest ./...

Testing with experimental synctest

GODEBUG=asynctimerchan=0 go test -tags=goexperiment.synctest ./...

Production build with zero overhead

go build -tags=deadlock_disable ./...


## Configuring go-deadlock

Have a look at [Opts](https://pkg.go.dev/github.com/sasha-s/go-deadlock#pkg-variables).

* `Opts.Disable`: disables deadlock detection altogether (runtime option; see also `deadlock_disable` build tag)
* `Opts.DisableLockOrderDetection`: disables lock order based deadlock detection.
* `Opts.DeadlockTimeout`: blocking on mutex for longer than DeadlockTimeout is considered a deadlock. ignored if negative
* `Opts.OnPotentialDeadlock`: callback for then deadlock is detected
* `Opts.MaxMapSize`: size of happens before // happens after table
* `Opts.PrintAllCurrentGoroutines`:  dump stacktraces of all goroutines when inconsistent locking is detected, verbose
* `Opts.LogBuf`: where to write deadlock info/stacktraces
* `Opts.TimerPool`: controls timer pooling behavior (auto-configured based on build tags)