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
@@ -33,3 +34,18 @@ jobs:
         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()
+}

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

sync_disable.go

@@ -0,0 +1,55 @@
+//go:build deadlock_disable && !go1.18
+
+package deadlock
+
+import "sync"
+
+// StandardMutex wraps sync.Mutex with no deadlock detection
+type StandardMutex struct {
+	mu sync.Mutex
+}
+
+func (m *StandardMutex) Lock() {
+	m.mu.Lock()
+}
+
+func (m *StandardMutex) Unlock() {
+	m.mu.Unlock()
+}
+
+func (m *StandardMutex) TryLock() bool {
+	panic("TryLock requires Go 1.18 or later")
+}
+
+// StandardRWMutex wraps sync.RWMutex with no deadlock detection
+type StandardRWMutex struct {
+	mu sync.RWMutex
+}
+
+func (m *StandardRWMutex) Lock() {
+	m.mu.Lock()
+}
+
+func (m *StandardRWMutex) Unlock() {
+	m.mu.Unlock()
+}
+
+func (m *StandardRWMutex) RLock() {
+	m.mu.RLock()
+}
+
+func (m *StandardRWMutex) RUnlock() {
+	m.mu.RUnlock()
+}
+
+func (m *StandardRWMutex) TryLock() bool {
+	panic("TryLock requires Go 1.18 or later")
+}
+
+func (m *StandardRWMutex) TryRLock() bool {
+	panic("TryRLock requires Go 1.18 or later")
+}
+
+func (m *StandardRWMutex) RLocker() sync.Locker {
+	return m.mu.RLocker()
+}

sync_disable_go118.go

@@ -0,0 +1,55 @@
+//go:build deadlock_disable && go1.18
+
+package deadlock
+
+import "sync"
+
+// StandardMutex wraps sync.Mutex with no deadlock detection
+type StandardMutex struct {
+	mu sync.Mutex
+}
+
+func (m *StandardMutex) Lock() {
+	m.mu.Lock()
+}
+
+func (m *StandardMutex) Unlock() {
+	m.mu.Unlock()
+}
+
+func (m *StandardMutex) TryLock() bool {
+	return m.mu.TryLock()
+}
+
+// StandardRWMutex wraps sync.RWMutex with no deadlock detection
+type StandardRWMutex struct {
+	mu sync.RWMutex
+}
+
+func (m *StandardRWMutex) Lock() {
+	m.mu.Lock()
+}
+
+func (m *StandardRWMutex) Unlock() {
+	m.mu.Unlock()
+}
+
+func (m *StandardRWMutex) RLock() {
+	m.mu.RLock()
+}
+
+func (m *StandardRWMutex) RUnlock() {
+	m.mu.RUnlock()
+}
+
+func (m *StandardRWMutex) TryLock() bool {
+	return m.mu.TryLock()
+}
+
+func (m *StandardRWMutex) TryRLock() bool {
+	return m.mu.TryRLock()
+}
+
+func (m *StandardRWMutex) RLocker() sync.Locker {
+	return m.mu.RLocker()
+}

sync_mutex_go118.go

@@ -1,5 +1,5 @@
-//go:build !goexperiment.synctest && go1.18
-// +build !goexperiment.synctest,go1.18
+//go:build !goexperiment.synctest && !deadlock_synctest && !deadlock_disable && go1.18
+// +build !goexperiment.synctest,!deadlock_synctest,!deadlock_disable,go1.18
 
 package deadlock
 

sync_mutex_legacy.go

@@ -1,5 +1,5 @@
-//go:build !goexperiment.synctest && !go1.18
-// +build !goexperiment.synctest,!go1.18
+//go:build !goexperiment.synctest && !deadlock_synctest && !deadlock_disable && !go1.18
+// +build !goexperiment.synctest,!deadlock_synctest,!deadlock_disable,!go1.18
 
 package deadlock
 

synctest_channel_test.go

@@ -1,4 +1,4 @@
-//go:build goexperiment.synctest
+//go:build goexperiment.synctest && go1.25
 
 package deadlock