sync

sync包提供了基本的同步基元，如互斥锁。除了Once和WaitGroup类型，大部分都是适用于低水平程序线程，高水平的同步使用channel通信更好一些。

本包的类型的值不应被拷贝。

type Locker

type Locker interface {
    Lock()
    Unlock()
}

Locker接口代表一个可以加锁和解锁的对象。

type Once

type Once struct {
    // done indicates whether the action has been performed.
    // It is first in the struct because it is used in the hot path.
    // The hot path is inlined at every call site.
    // Placing done first allows more compact instructions on some architectures (amd64/x86),
    // and fewer instructions (to calculate offset) on other architectures.
    done uint32
    m    Mutex
}

Once是只执行一次动作的对象。

func main() {
   var once sync.Once
   onceBody := func() {
      fmt.Println("Only once")
   }
   done := make(chan bool)
   for i := 0; i < 10; i++ {
      go func() {
         once.Do(onceBody)
         done <- true
      }()
   }
   for i := 0; i < 10; i++ {
      <-done
   }
   // Only once
}

func (*Once) Do

func (o *Once) Do(f func())

Do方法当且仅当第一次被调用时才执行函数f。换句话说，给定变量：

var once Once

如果once.Do(f)被多次调用，只有第一次调用会执行f，即使f每次调用Do 提供的f值不同。需要给每个要执行仅一次的函数都建立一个Once类型的实例。

Do用于必须刚好运行一次的初始化。因为f是没有参数的，因此可能需要使用闭包来提供给Do方法调用：

config.once.Do(func() { config.init(filename) })

因为只有f返回后Do方法才会返回，f若引起了Do的调用，会导致死锁。

type Mutex

type Mutex struct {
    state int32
    sema  uint32
}

Mutex是一个互斥锁，可以创建为其他结构体的字段；零值为解锁状态。Mutex类型的锁和线程无关，可以由不同的线程加锁和解锁。

func (*Mutex) Lock

func (m *Mutex) Lock()

Lock方法锁住m，如果m已经加锁，则阻塞直到m解锁。

func (*Mutex) Unlock

func (m *Mutex) Unlock()

Unlock方法解锁m，如果m未加锁会导致运行时错误。锁和线程无关，可以由不同的线程加锁和解锁。

type RWMutex

type RWMutex struct {
    w           Mutex  // held if there are pending writers
    writerSem   uint32 // semaphore for writers to wait for completing readers
    readerSem   uint32 // semaphore for readers to wait for completing writers
    readerCount int32  // number of pending readers
    readerWait  int32  // number of departing readers
}

RWMutex是读写互斥锁。该锁可以被同时多个读取者持有或唯一个写入者持有。RWMutex可以创建为其他结构体的字段；零值为解锁状态。RWMutex类型的锁也和线程无关，可以由不同的线程加读取锁/写入和解读取锁/写入锁。

func (*RWMutex) Lock

func (rw *RWMutex) Lock()

Lock方法将rw锁定为写入状态，禁止其他线程读取或者写入。

func (*RWMutex) Unlock

func (rw *RWMutex) Unlock()

Unlock方法解除rw的写入锁状态，如果m未加写入锁会导致运行时错误。

func (*RWMutex) RLock]

func (rw *RWMutex) RLock()

RLock方法将rw锁定为读取状态，禁止其他线程写入，但不禁止读取。

func (*RWMutex) RUnlock

func (rw *RWMutex) RUnlock()

Runlock方法解除rw的读取锁状态，如果m未加读取锁会导致运行时错误。

func (*RWMutex) RLocker

func (rw *RWMutex) RLocker() Locker

Rlocker方法返回一个互斥锁，通过调用rw.Rlock和rw.Runlock实现了Locker接口。

type Cond

type Cond struct {
    // 在观测或更改条件时L会冻结
    L Locker
    // 包含隐藏或非导出字段
}

Cond实现了一个条件变量，一个线程集合地，供线程等待或者宣布某事件的发生。

每个Cond实例都有一个相关的锁（一般是Mutex或RWMutex类型的值），它必须在改变条件时或者调用Wait方法时保持锁定。Cond可以创建为其他结构体的字段，Cond在开始使用后不能被拷贝。

func NewCond

func NewCond(l Locker) *Cond

使用锁l创建一个*Cond。

func (*Cond) Broadcast

func (c *Cond) Broadcast()

Broadcast唤醒所有等待c的线程。调用者在调用本方法时，建议（但并非必须）保持c.L的锁定。

func (*Cond) Signal

func (c *Cond) Signal()

Signal唤醒等待c的一个线程（如果存在）。调用者在调用本方法时，建议（但并非必须）保持c.L的锁定。

func (*Cond) Wait

func (c *Cond) Wait()

Wait自行解锁c.L并阻塞当前线程，在之后线程恢复执行时，Wait方法会在返回前锁定c.L。和其他系统不同，Wait除非被Broadcast或者Signal唤醒，不会主动返回。

因为线程中Wait方法是第一个恢复执行的，而此时c.L未加锁。调用者不应假设Wait恢复时条件已满足，相反，调用者应在循环中等待：

c.L.Lock()
for !condition() {
    c.Wait()
}
... make use of condition ...
c.L.Unlock()

type WaitGroup

type WaitGroup struct {
    noCopy noCopy

    // 64-bit value: high 32 bits are counter, low 32 bits are waiter count.
    // 64-bit atomic operations require 64-bit alignment, but 32-bit
    // compilers do not ensure it. So we allocate 12 bytes and then use
    // the aligned 8 bytes in them as state, and the other 4 as storage
    // for the sema.
    state1 [3]uint32
}

WaitGroup用于等待一组线程的结束。父线程调用Add方法来设定应等待的线程的数量。每个被等待的线程在结束时应调用Done方法。同时，主线程里可以调用Wait方法阻塞至所有线程结束。

func main() {
   var wg sync.WaitGroup
   var urls = []string{
      "http://www.golang.org/",
      "http://www.google.com/",
      "http://www.somestupidname.com/",
   }
   for _, url := range urls {
      // Increment the WaitGroup counter.
      wg.Add(1)
      // Launch a goroutine to fetch the URL.
      go func(url string) {
         // Decrement the counter when the goroutine completes.
         defer wg.Done()
         // Fetch the URL.
         http.Get(url)
      }(url)
   }
   // Wait for all HTTP fetches to complete.
   wg.Wait()
}

func (*WaitGroup) Add

func (wg *WaitGroup) Add(delta int)

Add方法向内部计数加上delta，delta可以是负数；如果内部计数器变为0，Wait方法阻塞等待的所有线程都会释放，如果计数器小于0，方法panic。注意Add加上正数的调用应在Wait之前，否则Wait可能只会等待很少的线程。一般来说本方法应在创建新的线程或者其他应等待的事件之前调用。

func (*WaitGroup) Done

func (wg *WaitGroup) Done()

Done方法减少WaitGroup计数器的值，应在线程的最后执行。

func (*WaitGroup) Wait

func (wg *WaitGroup) Wait()

Wait方法阻塞直到WaitGroup计数器减为0。

type Pool

type Pool struct {
    // 可选参数New指定一个函数在Get方法可能返回nil时来生成一个值
    // 该参数不能在调用Get方法时被修改
    New func() interface{}
    // 包含隐藏或非导出字段
}

Pool是一个可以分别存取的临时对象的集合。

Pool中保存的任何item都可能随时不做通告的释放掉。如果Pool持有该对象的唯一引用，这个item就可能被回收。

Pool可以安全的被多个线程同时使用。

Pool的目的是缓存申请但未使用的item用于之后的重用，以减轻GC的压力。也就是说，让创建高效而线程安全的空闲列表更容易。但Pool并不适用于所有空闲列表。

Pool的合理用法是用于管理一组静静的被多个独立并发线程共享并可能重用的临时item。Pool提供了让多个线程分摊内存申请消耗的方法。

Pool的一个好例子在fmt包里。该Pool维护一个动态大小的临时输出缓存仓库。该仓库会在过载（许多线程活跃的打印时）增大，在沉寂时缩小。

另一方面，管理着短寿命对象的空闲列表不适合使用Pool，因为这种情况下内存申请消耗不能很好的分配。这时应该由这些对象自己实现空闲列表。

func (*Pool) Get

func (p *Pool) Get() interface{}

Get方法从池中选择任意一个item，删除其在池中的引用计数，并提供给调用者。Get方法也可能选择无视内存池，将其当作空的。调用者不应认为Get的返回这和传递给Put的值之间有任何关系。

假使Get方法没有取得item：如p.New非nil，Get返回调用p.New的结果；否则返回nil。

func (*Pool) Put

func (p *Pool) Put(x interface{})

Put方法将x放入池中。

• atomic

atomic

atomic包提供了底层的原子级内存操作，对于同步算法的实现很有用。

这些函数必须谨慎地保证正确使用。除了某些特殊的底层应用，使用通道或者sync包的函数/类型实现同步更好。

应通过通信来共享内存，而不通过共享内存实现通信。

被SwapT系列函数实现的交换操作，在原子性上等价于：

old = *addr
*addr = new
return old

CompareAndSwapT系列函数实现的比较-交换操作，在原子性上等价于：

if *addr == old {
    *addr = new
    return true
}
return false

AddT 系列函数实现加法操作，在原子性上等价于：

*addr += delta
return *addr

LoadT和StoreT系列函数实现的加载和保持操作，在原子性上等价于："return addr"和"addr = val"。

func LoadInt32

func LoadInt32(addr *int32) (val int32)

LoadInt32原子性的获取*addr的值。

func LoadInt64

func LoadInt64(addr *int64) (val int64)

LoadInt64原子性的获取*addr的值。

func LoadUint32

func LoadUint32(addr *uint32) (val uint32)

LoadUint32原子性的获取*addr的值。

func LoadUint64

func LoadUint64(addr *uint64) (val uint64)

LoadUint64原子性的获取*addr的值。

func LoadUintptr

func LoadUintptr(addr *uintptr) (val uintptr)

LoadUintptr原子性的获取*addr的值。

func LoadPointer

func LoadPointer(addr *unsafe.Pointer) (val unsafe.Pointer)

LoadPointer原子性的获取*addr的值。

func StoreInt32

func StoreInt32(addr *int32, val int32)

StoreInt32原子性的将val的值保存到*addr。

func StoreInt64

func StoreInt64(addr *int64, val int64)

StoreInt64原子性的将val的值保存到*addr。

func StoreUint32

func StoreUint32(addr *uint32, val uint32)

StoreUint32原子性的将val的值保存到*addr。

func StoreUint64

func StoreUint64(addr *uint64, val uint64)

StoreUint64原子性的将val的值保存到*addr。

func StoreUintptr

func StoreUintptr(addr *uintptr, val uintptr)

StoreUintptr原子性的将val的值保存到*addr。

func StorePointer

func StorePointer(addr *unsafe.Pointer, val unsafe.Pointer)

StorePointer原子性的将val的值保存到*addr。

func AddInt32

func AddInt32(addr *int32, delta int32) (new int32)

AddInt32原子性的将val的值添加到*addr并返回新值。

func AddInt64

func AddInt64(addr *int64, delta int64) (new int64)

AddInt64原子性的将val的值添加到*addr并返回新值。

func AddUint32

func AddUint32(addr *uint32, delta uint32) (new uint32)

AddUint32原子性的将val的值添加到*addr并返回新值。

如要减去一个值c，调用AddUint32(&x, ^uint32(c-1))；特别的，让x减1，调用AddUint32(&x, ^uint32(0))。

func AddUint64

func AddUint64(addr *uint64, delta uint64) (new uint64)

AddUint64原子性的将val的值添加到*addr并返回新值。

如要减去一个值c，调用AddUint64(&x, ^uint64(c-1))；特别的，让x减1，调用AddUint64(&x, ^uint64(0))。

func AddUintptr

func AddUintptr(addr *uintptr, delta uintptr) (new uintptr)

AddUintptr原子性的将val的值添加到*addr并返回新值。

func SwapInt32

func SwapInt32(addr *int32, new int32) (old int32)

SwapInt32原子性的将新值保存到*addr并返回旧值。

func SwapInt64

func SwapInt64(addr *int64, new int64) (old int64)

SwapInt64原子性的将新值保存到*addr并返回旧值。

func SwapUint32

func SwapUint32(addr *uint32, new uint32) (old uint32)

SwapUint32原子性的将新值保存到*addr并返回旧值。

func SwapUint64

func SwapUint64(addr *uint64, new uint64) (old uint64)

SwapUint64原子性的将新值保存到*addr并返回旧值。

func SwapUintptr

func SwapUintptr(addr *uintptr, new uintptr) (old uintptr)

SwapUintptr原子性的将新值保存到*addr并返回旧值。

func SwapPointer

func SwapPointer(addr *unsafe.Pointer, new unsafe.Pointer) (old unsafe.Pointer)

SwapPointer原子性的将新值保存到*addr并返回旧值。

func CompareAndSwapInt32

func CompareAndSwapInt32(addr *int32, old, new int32) (swapped bool)

CompareAndSwapInt32原子性的比较addr和old，如果相同则将new赋值给addr并返回真。

func CompareAndSwapInt64

func CompareAndSwapInt64(addr *int64, old, new int64) (swapped bool)

CompareAndSwapInt64原子性的比较addr和old，如果相同则将new赋值给addr并返回真。

func CompareAndSwapUint32

func CompareAndSwapUint32(addr *uint32, old, new uint32) (swapped bool)

CompareAndSwapUint32原子性的比较addr和old，如果相同则将new赋值给addr并返回真。

func CompareAndSwapUint64

func CompareAndSwapUint64(addr *uint64, old, new uint64) (swapped bool)

CompareAndSwapUint64原子性的比较addr和old，如果相同则将new赋值给addr并返回真。

func CompareAndSwapUintptr

func CompareAndSwapUintptr(addr *uintptr, old, new uintptr) (swapped bool)

CompareAndSwapUintptr原子性的比较addr和old，如果相同则将new赋值给addr并返回真。

func CompareAndSwapPointer

func CompareAndSwapPointer(addr *unsafe.Pointer, old, new unsafe.Pointer) (swapped bool)

CompareAndSwapPointer原子性的比较addr和old，如果相同则将new赋值给addr并返回真。

Bugs

☞ 在x86-32构架芯片上，64位函数使用的指令在Pentium MMX之前是不可用的；在非Linux的ARM芯片上，64位函数使用的指令在ARMv6k core之前是不可用的。不管是ARM又或x86-32芯片，安排原子性访问的64位word的64位对齐都是调用者的责任。可以依靠全局变量或申请的切片/结构体的第一个word来实现64位对齐。