Fix/synctest compatibility (#42)

* Add testing/synctest compatibility for go-deadlock

Support testing/synctest:

- DisableTimerPool option to make sure times stay within the bubble
- channel-based mutex/rwmutex for

* fmt

* Fix synctest compatibility

- ChannelMutex/ChannelRWMutex for synctest compatibility
- Fixes timer pool handling: uses non-blocking drain to avoid deadlocks
  in synctest bubbles
- Support Go 1.25 native synctest tests

Fixes: #42
Manually tested with: dunglas/mercure#1099

* Add GODEBUG=asynctimerchan=0 to CI for Go 1.25 synctest compatibility

* Add build tag system with synctest compatibility and disable mode
+ sync_disable.go for zero-overhead mode (-tags=deadlock_disable)
+ synctest compatibility mode (-tags=goexperiment.synctest)
+ buildtag_test.go and scripts/test-buildtags.sh

Author: sasha-s

.github/workflows/go.yml

@@ -17,6 +17,7 @@ jobs:
           - "1.20"
           - "1.22"
           - "1.23"
+          - "1.24"
           - "1.25"
     steps:
       - uses: actions/checkout@v4
@@ -31,3 +32,20 @@ jobs:
 
       - name: Test
         run: go test -v -bench=. -coverprofile=coverage.txt ./...
+        env:
+          GODEBUG: asynctimerchan=0
+
+      - name: Test with deadlock_disable tag
+        run: go test -v -tags=deadlock_disable ./...
+
+      - name: Test with goexperiment.synctest tag (Go 1.24+)
+        if: matrix.go == '1.24' || matrix.go == '1.25'
+        run: go test -v -tags=goexperiment.synctest ./...
+        env:
+          GODEBUG: asynctimerchan=0
+
+      - name: Test with deadlock_synctest tag (Go 1.25+)
+        if: matrix.go == '1.25'
+        run: go test -v -tags=deadlock_synctest ./...
+        env:
+          GODEBUG: asynctimerchan=0

Readme.md

@@ -172,16 +172,45 @@ func main() {
 	rlockTwice()
 }
 ```
+## Build Tags and Compatibility Modes
+
+go-deadlock supports multiple build configurations for different use cases:
+
+* **Normal mode** (default): Full deadlock detection with timer pooling
+* **Synctest mode**: Compatible with Go's `testing/synctest` package - use either:
+  * `-tags=deadlock_synctest` (recommended for Go 1.25+)
+  * `-tags=goexperiment.synctest` (for experimental synctest)
+* **Disabled mode** (`-tags=deadlock_disable`): Zero overhead, no detection
+
+**Why synctest mode?** `sync.Mutex` is not durably blocking in synctest bubbles, but channels are. Synctest mode uses channel-based mutexes to ensure proper behavior with `testing/synctest`.
+
+### Quick Examples
+
+```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
+* `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)
+
 
-	

buildtag_test.go

@@ -0,0 +1,157 @@
+//go:build go1.18
+
+package deadlock
+
+import (
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestBuildTagMutexWorks tests that mutexes work correctly regardless of build tags
+func TestBuildTagMutexWorks(t *testing.T) {
+	var mu Mutex
+	var counter int
+
+	// Simple lock/unlock
+	mu.Lock()
+	counter++
+	mu.Unlock()
+
+	if counter != 1 {
+		t.Errorf("Expected counter to be 1, got %d", counter)
+	}
+
+	// Concurrent access
+	done := make(chan bool)
+	for i := 0; i < 10; i++ {
+		go func() {
+			mu.Lock()
+			counter++
+			mu.Unlock()
+			done <- true
+		}()
+	}
+
+	for i := 0; i < 10; i++ {
+		<-done
+	}
+
+	if counter != 11 {
+		t.Errorf("Expected counter to be 11, got %d", counter)
+	}
+}
+
+// TestBuildTagRWMutexWorks tests that RWMutexes work correctly regardless of build tags
+func TestBuildTagRWMutexWorks(t *testing.T) {
+	var mu RWMutex
+	var counter int
+
+	// Write lock
+	mu.Lock()
+	counter++
+	mu.Unlock()
+
+	// Read lock
+	mu.RLock()
+	_ = counter
+	mu.RUnlock()
+
+	// Multiple readers
+	done := make(chan bool)
+	for i := 0; i < 5; i++ {
+		go func() {
+			mu.RLock()
+			_ = counter
+			time.Sleep(1 * time.Millisecond)
+			mu.RUnlock()
+			done <- true
+		}()
+	}
+
+	for i := 0; i < 5; i++ {
+		<-done
+	}
+
+	// Writer after readers
+	mu.Lock()
+	counter++
+	mu.Unlock()
+
+	if counter != 2 {
+		t.Errorf("Expected counter to be 2, got %d", counter)
+	}
+}
+
+// TestBuildTagTryLock tests TryLock functionality
+func TestBuildTagTryLock(t *testing.T) {
+	var mu Mutex
+
+	// TryLock should succeed when unlocked
+	if !mu.TryLock() {
+		// For Go < 1.18, TryLock panics, so we skip this test
+		if testing.Short() {
+			t.Skip("TryLock not available in this Go version")
+		}
+		t.Error("TryLock should succeed on unlocked mutex")
+	}
+
+	// TryLock should fail when locked
+	result := make(chan bool, 1)
+	go func() {
+		result <- mu.TryLock()
+	}()
+
+	select {
+	case r := <-result:
+		if r {
+			t.Error("TryLock should fail on locked mutex")
+		}
+	case <-time.After(100 * time.Millisecond):
+		// This is okay - TryLock might block briefly
+	}
+
+	mu.Unlock()
+}
+
+// TestBuildTagRWMutexTryLock tests RWMutex TryLock/TryRLock
+func TestBuildTagRWMutexTryLock(t *testing.T) {
+	var mu RWMutex
+
+	// TryRLock should succeed when unlocked
+	if !mu.TryRLock() {
+		if testing.Short() {
+			t.Skip("TryRLock not available in this Go version")
+		}
+		t.Error("TryRLock should succeed on unlocked RWMutex")
+	}
+
+	// Another TryRLock from a different goroutine should also succeed (multiple readers allowed)
+	done := make(chan bool)
+	go func() {
+		if !mu.TryRLock() {
+			t.Error("TryRLock should succeed when already read-locked by another goroutine")
+		}
+		mu.RUnlock()
+		done <- true
+	}()
+	<-done
+
+	mu.RUnlock()
+
+	// TryLock should succeed when unlocked
+	if !mu.TryLock() {
+		t.Error("TryLock should succeed on unlocked RWMutex")
+	}
+
+	mu.Unlock()
+}
+
+// TestCompatibilityWithStdlib tests that our types are compatible with stdlib expectations
+func TestCompatibilityWithStdlib(t *testing.T) {
+	var _ sync.Locker = &Mutex{}
+
+	var rwmu RWMutex
+	var _ sync.Locker = &rwmu
+	var _ sync.Locker = rwmu.RLocker()
+}

deadlock.go

@@ -12,6 +12,18 @@ import (
 	"github.com/petermattis/goid"
 )
 
+// TimerPoolMode controls timer pooling behavior
+type TimerPoolMode int
+
+const (
+	// TimerPoolDefault automatically chooses based on build environment
+	TimerPoolDefault TimerPoolMode = iota
+	// TimerPoolEnabled always uses timer pooling for performance
+	TimerPoolEnabled
+	// TimerPoolDisabled disables timer pooling (required for testing/synctest)
+	TimerPoolDisabled
+)
+
 // Opts control how deadlock detection behaves.
 // Options are supposed to be set once at a startup (say, when parsing flags).
 var Opts = struct {
@@ -31,7 +43,12 @@ var Opts = struct {
 	MaxMapSize int
 	// Will dump stacktraces of all goroutines when inconsistent locking is detected.
 	PrintAllCurrentGoroutines bool
-	mu                        *sync.Mutex // Protects the LogBuf.
+	// Controls timer pooling behavior.
+	// TimerPoolDefault: Automatically choose based on build environment
+	// TimerPoolEnabled: Always use timer pooling
+	// TimerPoolDisabled: Never use timer pooling
+	TimerPool TimerPoolMode
+	mu        *sync.Mutex // Protects the LogBuf.
 	// Will print deadlock info to log buffer.
 	LogBuf io.Writer
 }{
@@ -75,7 +92,7 @@ var NewCond = sync.NewCond
 // A Mutex is a drop-in replacement for sync.Mutex.
 // Performs deadlock detection unless disabled in Opts.
 type Mutex struct {
-	mu sync.Mutex
+	mu StandardMutex
 }
 
 // Lock locks the mutex.
@@ -104,7 +121,7 @@ func (m *Mutex) Unlock() {
 // An RWMutex is a drop-in replacement for sync.RWMutex.
 // Performs deadlock detection unless disabled in Opts.
 type RWMutex struct {
-	mu sync.RWMutex
+	mu StandardRWMutex
 }
 
 // Lock locks rw for writing.
@@ -155,7 +172,7 @@ func (m *RWMutex) RUnlock() {
 // RLocker returns a Locker interface that implements
 // the Lock and Unlock methods by calling RLock and RUnlock.
 func (m *RWMutex) RLocker() sync.Locker {
-	return (*rlocker)(m)
+	return m.mu.RLocker()
 }
 
 func preLock(stack []uintptr, p interface{}) {
@@ -194,6 +211,10 @@ func lock(lockFn func(), ptr interface{}) {
 var timersPool sync.Pool
 
 func acquireTimer(d time.Duration) *time.Timer {
+	if shouldDisableTimerPool() {
+		return time.NewTimer(Opts.DeadlockTimeout)
+	}
+
 	t, ok := timersPool.Get().(*time.Timer)
 	if ok {
 		_ = t.Reset(d)
@@ -203,9 +224,22 @@ func acquireTimer(d time.Duration) *time.Timer {
 }
 
 func releaseTimer(t *time.Timer) {
-	if !t.Stop() {
-		<-t.C
+	stopped := t.Stop()
+
+	// Skip timer pooling if disabled
+	if shouldDisableTimerPool() {
+		return
+	}
+
+	// Use non-blocking drain to avoid hanging in synctest bubbles.
+	// Blocking on t.C can deadlock when testing/synctest virtualizes time.
+	if !stopped {
+		select {
+		case <-t.C:
+		default:
+		}
 	}
+
 	timersPool.Put(t)
 }
 
@@ -356,11 +390,6 @@ func (l *lockOrder) postUnlock(p interface{}) {
 	l.mu.Unlock()
 }
 
-type rlocker RWMutex
-
-func (r *rlocker) Lock()   { (*RWMutex)(r).RLock() }
-func (r *rlocker) Unlock() { (*RWMutex)(r).RUnlock() }
-
 // Under lo.mu Locked.
 func (l *lockOrder) other(ptr interface{}) {
 	empty := true

deadlock_map.go

@@ -1,3 +1,4 @@
+//go:build go1.9
 // +build go1.9
 
 package deadlock

go.mod

@@ -1,3 +1,5 @@
 module github.com/sasha-s/go-deadlock
 
 require github.com/petermattis/goid v0.0.0-20250813065127-a731cc31b4fe
+
+replace github.com/sasha-s/go-deadlock => /src/go-deadlock

mutex.go

@@ -0,0 +1,21 @@
+package deadlock
+
+import "sync"
+
+// MutexImpl defines the interface for mutex implementations
+type MutexImpl interface {
+	Lock()
+	Unlock()
+	TryLock() bool
+}
+
+// RWMutexImpl defines the interface for rwmutex implementations
+type RWMutexImpl interface {
+	Lock()
+	Unlock()
+	RLock()
+	RUnlock()
+	TryLock() bool
+	TryRLock() bool
+	RLocker() sync.Locker
+}