used condition compile to replace default sync package. add README file.

bg5sbk · bg5sbk · commit cac73a841583 · 2014-12-03T22:49:17.000+08:00
diff --git a/README.md b/README.md
@@ -1,21 +1,5 @@
-介绍
-====
+[English](http://github.com/funny/sync/blob/master/README_EN.md)
+---------
 
-这个包用来在开发调试期，帮助排查程序中的死锁情况。
-
-可以直接替代原生的`sync`包，在禁用死锁检查的时候，只会有非常小的性能差异，具体可以看Benchmark结果。
-
-原理
-====
-
-在开启死锁检查的时候，系统会维护一份全局的锁等待列表，其次每个锁都会有当前使用者的信息。
-
-当一个goroutine要等待一个锁的时候，系统会到全局的等待列表里面查找当前这个锁的使用者，是否间接或直接的正在等待当前请求锁的这个goroutine。
-
-死锁不一定只发生在两个goroutine之间，极端情况也可能是一个链条状的依赖关系，又或者可能出现自身重复加锁的死锁情况。
-
-当出现死锁的时候，系统将提取死锁链上的所有goroutine的堆栈跟踪信息，方便排查故障原因。
-
-因为需要维护一份全局的锁等待列表，所以这里会出现额外并且集中的一个全局锁开销，会导致明显的程序的并发性能下降。
-
-全局锁的问题还会再继续研究和加以改进，但是目前这个包是不能用于生产环境的，只能用在开发和调试期作为死锁诊断的辅助工具。
+[中文说明](http://github.com/funny/sync/blob/master/README_CN.md)
+---------
diff --git a/README_CN.md b/README_CN.md
@@ -0,0 +1,74 @@
+介绍
+====
+
+这个包用来在开发调试期，帮助排查程序中的死锁情况。
+
+用法
+====
+
+通常我们项目中引用到原生`sync`包的代码会像这样：
+
+```go
+package myapp
+
+import "sync"
+
+var MyLock sync.Mutex
+
+func MyFunc() {
+	MyLock.Lock()
+	defer MyLock.Unlock()
+
+	// .......
+}
+```
+
+只需要将原来引用`sync`的代码改为引用`github.com/funny/sync`包，不需要修改别的代码：
+
+
+```go
+package myapp
+
+import "github.com/funny/sync"
+
+var MyLock sync.Mutex
+
+func MyFunc() {
+	MyLock.Lock()
+	defer MyLock.Unlock()
+
+	// .......
+}
+```
+
+这时候死锁诊断还没有被启用，因为做了条件编译，所以锁的开销跟原生`sync`包是一样的。
+
+当需要编译一个带死锁诊断的版本的时候，在`go build --tags`列表中加入`deadlock`标签。
+
+例如这样：
+
+```
+go build -tags 'deadlock' myproject
+```
+
+同样这个标签也用于单元测试，否则默认的单元测试会死锁：
+
+```
+go test -tags 'deadlock'
+```
+
+
+原理
+====
+
+在开启死锁检查的时候，系统会维护一份全局的锁等待列表，其次每个锁都会有当前使用者的信息。
+
+当一个goroutine要等待一个锁的时候，系统会到全局的等待列表里面查找当前这个锁的使用者，是否间接或直接的正在等待当前请求锁的这个goroutine。
+
+死锁不一定只发生在两个goroutine之间，极端情况也可能是一个链条状的依赖关系，又或者可能出现自身重复加锁的死锁情况。
+
+当出现死锁的时候，系统将提取死锁链上的所有goroutine的堆栈跟踪信息，方便排查故障原因。
+
+因为需要维护一份全局的锁等待列表，所以这里会出现额外并且集中的一个全局锁开销，会导致明显的程序的并发性能下降。
+
+全局锁的问题还会再继续研究和加以改进，但是目前这个包是不能用于生产环境的，只能用在开发和调试期作为死锁诊断的辅助工具。
diff --git a/README_EN.md b/README_EN.md
@@ -0,0 +1,73 @@
+Introduction
+============
+
+This package is used to detect deadlock in Go program.
+
+Usage
+=====
+
+Normally, we import default `sync` package in our project like this：
+
+```go
+package myapp
+
+import "sync"
+
+var MyLock sync.Mutex
+
+func MyFunc() {
+	MyLock.Lock()
+	defer MyLock.Unlock()
+
+	// .......
+}
+```
+
+Just replace the default `sync` to `github.com/funny/sync`, no need to change others：
+
+
+```go
+package myapp
+
+import "github.com/funny/sync"
+
+var MyLock sync.Mutex
+
+func MyFunc() {
+	MyLock.Lock()
+	defer MyLock.Unlock()
+
+	// .......
+}
+```
+
+Currently, deadlock detection not yet enabled, the performance of `Mutext` and `RWMutex` just like default.
+
+When you need to compile a deadlock detection enabled version. Just add `deadlock` tag into `go build --tags` command.
+
+For example:
+
+```
+go build -tags 'deadlock' myproject
+```
+
+This tag used for the unit test too. Otherwise the default unit test will deadlock:
+
+```
+go test -tags 'deadlock'
+```
+
+How it works
+============
+
+When deadlock detection enabled, system will maintain a global lock waiting list, and each `Mutex` and `RWMutex` will keep owner goroutine's information.
+
+When a goroutine will waiting a lock, system will lookup the lock owner goroutine is whether waiting for the requester goroutine in directly or indirectly.
+
+Deadlock not only happens between two goroutines, sometimes the deadlock is a link, and deadlock happens when a goroutine repeat lock a `Mutext` too.
+
+When deadlock happens, system will dump stack trace of the gorotuines in the deadlock link.
+
+Because we need a global lock waiting list, so the deadlock detection will drop the performance.
+
+So, please don't use deadlock detection in production environment.
diff --git a/common.go b/common.go
@@ -0,0 +1,14 @@
+package sync
+
+import "sync"
+
+type Cond sync.Cond
+
+func NewCond(l Locker) *Cond {
+	return (*Cond)(sync.NewCond(l))
+}
+
+type Locker sync.Locker
+type Once sync.Once
+type Pool sync.Pool
+type WaitGroup sync.WaitGroup
diff --git a/dummy.go b/dummy.go
@@ -0,0 +1,13 @@
+// +build !deadlock
+
+package sync
+
+import "sync"
+
+type Mutex struct {
+	sync.Mutex
+}
+
+type RWMutex struct {
+	sync.RWMutex
+}
diff --git a/sync.go b/sync.go
@@ -1,3 +1,5 @@
+// +build deadlock
+
 package sync
 
 import (
@@ -11,7 +13,41 @@ import (
 	"sync/atomic"
 )
 
-var WatchDeadLock int32 = 1
+type Mutex struct {
+	mutexInfo
+	sync.Mutex
+}
+
+func (m *Mutex) Lock() {
+	holder, elem := m.mutexInfo.wait()
+	m.Mutex.Lock()
+	m.mutexInfo.using(holder, elem)
+}
+
+func (m *Mutex) Unlock() {
+	m.mutexInfo.release()
+	m.Mutex.Unlock()
+}
+
+type RWMutex struct {
+	Mutex
+}
+
+func (rw *RWMutex) Lock() {
+	rw.Lock()
+}
+
+func (rw *RWMutex) Unlock() {
+	rw.Unlock()
+}
+
+func (rw *RWMutex) RLock() {
+	rw.Lock()
+}
+
+func (rw *RWMutex) RUnlock() {
+	rw.Unlock()
+}
 
 var (
 	lockMutex      = new(sync.Mutex)
@@ -33,7 +69,6 @@ func goroutine(id int32, stack []byte) []byte {
 type mutexInfo struct {
 	holder  int32
 	waiting *list.List
-	watch   bool
 }
 
 func (lock *mutexInfo) wait() (int32, *list.Element) {
@@ -85,47 +120,3 @@ func (lock *mutexInfo) using(holder int32, elem *list.Element) {
 func (lock *mutexInfo) release() {
 	atomic.StoreInt32(&lock.holder, 0)
 }
-
-type Mutex struct {
-	mutexInfo
-	sync.Mutex
-}
-
-func (m *Mutex) Lock() {
-	m.mutexInfo.watch = atomic.LoadInt32(&WatchDeadLock) == 1
-
-	if m.mutexInfo.watch {
-		holder, elem := m.mutexInfo.wait()
-		m.Mutex.Lock()
-		m.mutexInfo.using(holder, elem)
-	} else {
-		m.Mutex.Lock()
-	}
-}
-
-func (m *Mutex) Unlock() {
-	if m.mutexInfo.watch {
-		m.mutexInfo.release()
-	}
-	m.Mutex.Unlock()
-}
-
-type RWMutex struct {
-	Mutex
-}
-
-func (rw *RWMutex) Lock() {
-	rw.Lock()
-}
-
-func (rw *RWMutex) Unlock() {
-	rw.Unlock()
-}
-
-func (rw *RWMutex) RLock() {
-	rw.Lock()
-}
-
-func (rw *RWMutex) RUnlock() {
-	rw.Unlock()
-}
diff --git a/sync_test.go b/sync_test.go
@@ -22,18 +22,8 @@ func Benchmark_Lock2(b *testing.B) {
 	}
 }
 
-func Benchmark_Lock3(b *testing.B) {
-	WatchDeadLock = 0
-	var mutex Mutex
-	for i := 0; i < b.N; i++ {
-		mutex.Lock()
-		mutex.Unlock()
-	}
-	WatchDeadLock = 1
-}
-
 func Test_DeadLock1(t *testing.T) {
-	var testDone sync.WaitGroup
+	var testDone WaitGroup
 	testDone.Add(1)
 
 	go func() {
@@ -57,7 +47,7 @@ func Test_DeadLock1(t *testing.T) {
 }
 
 func Test_DeadLock2(t *testing.T) {
-	var testDone sync.WaitGroup
+	var testDone WaitGroup
 	testDone.Add(1)
 
 	go func() {
@@ -70,7 +60,7 @@ func Test_DeadLock2(t *testing.T) {
 		mutex1 Mutex
 		mutex2 Mutex
 
-		wait1 sync.WaitGroup
+		wait1 WaitGroup
 	)
 
 	wait1.Add(1)
@@ -94,7 +84,7 @@ func Test_DeadLock2(t *testing.T) {
 }
 
 func Test_DeadLock3(t *testing.T) {
-	var testDone sync.WaitGroup
+	var testDone WaitGroup
 	testDone.Add(1)
 
 	go func() {
@@ -108,8 +98,8 @@ func Test_DeadLock3(t *testing.T) {
 		mutex2 Mutex
 		mutex3 Mutex
 
-		wait1 sync.WaitGroup
-		wait2 sync.WaitGroup
+		wait1 WaitGroup
+		wait2 WaitGroup
 	)
 
 	wait1.Add(1)
