var sum int // 和
var mu sync.Mutex // 互斥鎖

// add 將 sum 加 1
func add() {
    // 獲取鎖，只能有一個協(xié)程獲取到鎖，
    // 其他協(xié)程需要阻塞等待鎖釋放才能獲取到鎖。
   mu.Lock()
   // 臨界區(qū)域
   sum++
   mu.Unlock()
}

func TestMutex(t *testing.T) {
   // 啟動 1000 個協(xié)程
   var wg sync.WaitGroup
   wg.Add(1000)

   for i := 0; i < 1000; i++ {
      go func() {
         // 每個協(xié)程里面調用 add()
         add()
         wg.Done()
      }()
   }

   // 等待所有協(xié)程執(zhí)行完畢
   wg.Wait()
   // 最終 sum 的值應該是 1000
   assert.Equal(t, 1000, sum)
}

// Set is used to store a new key/value pair exclusively for this context.
// It also lazy initializes  c.Keys if it was not used previously.
func (c *Context) Set(key string, value any) {
    // 獲取鎖
   c.mu.Lock()
    // 如果 Keys 還沒初始化，則進行初始化
   if c.Keys == nil {
      c.Keys = make(map[string]any)
   }

    // 設置鍵值對
   c.Keys[key] = value
    // 釋放鎖
   c.mu.Unlock()
}

// Get returns the value for the given key, ie: (value, true).
// If the value does not exist it returns (nil, false)
func (c *Context) Get(key string) (value any, exists bool) {
    // 獲取鎖
   c.mu.RLock()
    // 讀取 key
   value, exists = c.Keys[key]
    // 釋放鎖
   c.mu.RUnlock()
   return
}

var (
   // 保護 allPools 和 oldPools 的互斥鎖。
   allPoolsMu Mutex

   // allPools is the set of pools that have non-empty primary
   // caches. Protected by either 1) allPoolsMu and pinning or 2)
   // STW.
   allPools []*Pool

   // oldPools is the set of pools that may have non-empty victim
   // caches. Protected by STW.
   oldPools []*Pool
)

func (p *Pool) pinSlow() (*poolLocal, int) {
   // Retry under the mutex.
   // Can not lock the mutex while pinned.
   runtime_procUnpin()
   allPoolsMu.Lock() // 獲取鎖
   defer allPoolsMu.Unlock() // 函數(shù)返回的時候釋放鎖
   pid := runtime_procPin()
   // poolCleanup won't be called while we are pinned.
   s := p.localSize
   l := p.local
   if uintptr(pid) < s {
      return indexLocal(l, pid), pid
   }
   if p.local == nil {
      allPools = append(allPools, p) // 全局變量修改
   }
   // If GOMAXPROCS changes between GCs, we re-allocate the array and lose the old one.
   size := runtime.GOMAXPROCS(0)
   local := make([]poolLocal, size)
   atomic.StorePointer(&p.local, unsafe.Pointer(&local[0])) // store-release
   runtime_StoreReluintptr(&p.localSize, uintptr(size))     // store-release
   return &local[pid], pid
}

// Take takes the first element out of q if not empty.
func (q *Queue) Take() (any, bool) {
   // 獲取互斥鎖（只能有一個協(xié)程獲取到鎖）
   q.lock.Lock()
   // 函數(shù)返回的時候釋放互斥鎖（獲取到鎖的協(xié)程釋放鎖之后，其他協(xié)程才能進行搶占鎖）
   defer q.lock.Unlock()

   // 下面的代碼只有搶占到（也就是互斥鎖鎖定的代碼塊）
   if q.count == 0 {
      return nil, false
   }

   element := q.elements[q.head]
   q.head = (q.head + 1) % len(q.elements)
   q.count--

   return element, true
}

import (
   "fmt"
   "sync"
   "testing"
)

var mu sync.Mutex
var sum int

// 在鎖的保護下對 sum 做讀寫操作
func test() {
   mu.Lock()
   sum++
   mu.Unlock()
}

func TestMutex(t *testing.T) {
   var wg sync.WaitGroup
   wg.Add(1000)

   for i := 0; i < 500; i++ {
      go func() {
         test()
         wg.Done()
      }()

      // 位于臨界區(qū)外，也依然是可以對 sum 做讀寫操作的。
      sum++
   }

   wg.Wait()

   fmt.Println(sum)
}

type Mutex struct {
   state int32 // 狀態(tài)字段
   sema  uint32 // 信號量
}

const (
   mutexLocked      = 1 << iota // 表示有 goroutine 擁有鎖
   mutexWoken                   // 喚醒（就是第 2 位）
   mutexStarving                // 饑餓（第 3 位）
   mutexWaiterShift = iota      // 表示第 4 位開始，表示等待者的數(shù)量

   starvationThresholdNs = 1e6  // 1ms 進入饑餓模式的等待時間閾值
)

new |= mutexLocked

atomic.CompareAndSwapInt32(&m.state, old, new)

// Lock 獲取鎖。
// 如果鎖已在使用中，則調用 goroutine 將阻塞，直到互斥量可用。
func (m *Mutex) Lock() {
   // Fast path: grab unlocked mutex.
   // 上鎖成功則直接返回
   if atomic.CompareAndSwapInt32(&m.state, 0, mutexLocked) {
      return
   }

   // Slow path (outlined so that the fast path can be inlined)
   // 沒有上鎖成功，這個時候需要做的事情就有點多了。
   m.lockSlow()
}

// 獲取 mutex 鎖
func (m *Mutex) lockSlow() {
   var waitStartTime int64 // 當前協(xié)程開始等待的時間
   starving := false       // 當前協(xié)程是否是饑餓模式
   awoke := false          // 喚醒標志（是否當前協(xié)程就是被喚醒的協(xié)程）
   iter := 0               // 自旋次數(shù)（超過一定次數(shù)如果還沒能獲得鎖，就進入等待）
   old := m.state          // 舊的狀態(tài)，每次 for 循環(huán)會重新獲取當前的狀態(tài)字段

   for {
      // 自旋：目的是讓正在運行中的 goroutine 盡快獲取到鎖。
      // 兩種情況不會自旋：
      // 1. 饑餓模式：在饑餓模式下，鎖會直接交給等待隊列中的 goroutine，所以不會自旋。
      // 2. 鎖被釋放了：另外如果運行到這里的時候，發(fā)現(xiàn)鎖已經(jīng)被釋放了，也就不需要自旋了。
      if old&(mutexLocked|mutexStarving) == mutexLocked && runtime_canSpin(iter) {
         // 設置 mutexWoken 標識
         // 如果自旋是有意義的，則會進入到這里，嘗試設置 mutexWoken 標識。
         // 設置成功在持有鎖的 goroutine 獲取鎖的時候不會喚醒等待隊列中的 goroutine，下一個獲取鎖的就是當前 goroutine。
         if !awoke && old&mutexWoken == 0 && old>>mutexWaiterShift != 0 &&
            atomic.CompareAndSwapInt32(&m.state, old, old|mutexWoken) {
            // 各個判斷的含義：
            // !awoke 已經(jīng)被喚醒過一次了，說明當前協(xié)程是被從等待隊列中喚醒的協(xié)程/又或者已經(jīng)成功設置 mutexWoken 標識了，不需要再喚醒了。
            // old&mutexWoken == 0 如果不等于 0 說明有 goroutine 被喚醒了，不會嘗試設置 mutexWoken 標識
            // old>>mutexWaiterShift != 0 如果等待隊列為空，當前 goroutine 就是下一個搶占鎖的 goroutine
            // 前面的判斷都通過了，才會進行 CAS 操作嘗試設置 mutexWoken 標識
            awoke = true
         }
         runtime_doSpin() // 自旋
         iter++           // 自旋次數(shù) +1（超過一定次數(shù)會停止自旋）
         old = m.state    // 再次獲取鎖的最新狀態(tài)，之后會檢查是否鎖被釋放了
         continue         // 繼續(xù)下一次檢查
      }

      new := old
      // 饑餓模式下，新到達的 goroutines 必須排隊。
      // 不是饑餓狀態(tài)，直接競爭鎖。
      if old&mutexStarving == 0 {
         new |= mutexLocked
      }
      // 進入等待隊列的兩種情況：
      // 1. 鎖依然被占用。
      // 2. 進入了饑餓模式。
      if old&(mutexLocked|mutexStarving) != 0 {
         new += 1 << mutexWaiterShift // 等待者數(shù)量 +1
      }
       // 已經(jīng)等待超過了 1ms，且鎖被其他協(xié)程占用，則進入饑餓模式
      if starving && old&mutexLocked != 0 {
         new |= mutexStarving
      }
      // 喚醒之后，需要重置喚醒標志。
      // 不管有沒有獲取到鎖，都是要清除這個標識的：
      // 獲取到鎖肯定要清除，如果獲取到鎖，需要讓其他運行中的 goroutine 來搶占鎖；
      // 如果沒有獲取到鎖，goroutine 會阻塞，這個時候是需要持有鎖的 goroutine 來喚醒的，如果有 mutexWoken 標識，持有鎖的 goroutine 喚醒不了。
      if awoke {
         if new&mutexWoken == 0 {
            throw("sync: inconsistent mutex state")
         }
         new &^= mutexWoken // 重置喚醒標志
      }

      // 成功設置新狀態(tài)
      if atomic.CompareAndSwapInt32(&m.state, old, new) {
         // 原來鎖的狀態(tài)已釋放，并且不是饑餓狀態(tài)，正常請求到了鎖，返回
         if old&(mutexLocked|mutexStarving) == 0 { // 這意味著當前的 goroutine 成功獲取了鎖
            break
         }

         // 如果已經(jīng)被喚醒過，會被加入到等待隊列頭。
         queueLifo := waitStartTime != 0
         if waitStartTime == 0 {
            waitStartTime = runtime_nanotime()
         }
         // 阻塞等待
         // queueLifo 為 true，表示加入到隊列頭。否則，加入到隊列尾。
         // (首次加入隊列加入到隊尾，不是首次加入則加入隊頭，這樣等待最久的 goroutine 優(yōu)先能夠獲取到鎖。)
         runtime_SemacquireMutex(&m.sema, queueLifo, 1)
         // 從等待隊列中喚醒，檢查鎖是否應該進入饑餓模式。
         starving = starving || runtime_nanotime()-waitStartTime > starvationThresholdNs

         // 獲取當前的鎖最新狀態(tài)
         old = m.state
         // 如果鎖已經(jīng)處于饑餓狀態(tài)，直接搶到鎖，返回。
         // 饑餓模式下，被喚醒的協(xié)程可以直接獲取到鎖。
         // 新來的 goroutine 都需要進入隊列等待。
         if old&mutexStarving != 0 {
            // 如果這個 goroutine 被喚醒并且 Mutex 處于饑餓模式，P 的所有權已經(jīng)移交給我們，
            // 但 Mutex 處于不一致的狀態(tài)：mutexLocked 未設置，我們仍然被視為等待者。修復這個問題。
            if old&(mutexLocked|mutexWoken) != 0 || old>>mutexWaiterShift == 0 {
               throw("sync: inconsistent mutex state")
            }
            // 加鎖，并且減少等待者數(shù)量。
            // 實際上是兩步操作合成了一步：
            // 1. m.state = m.state + 1 （獲取鎖）
            // 2. m.state = m.state - 1<<mutexWaiterShift（waiter - 1）
            delta := int32(mutexLocked - 1<<mutexWaiterShift)
            // 清除饑餓狀態(tài)的兩種情況：
            // 1. 如果不需要進入饑餓模式（當前被喚醒的 goroutine 的等待時間小于 1ms）
            // 2. 原來的等待者數(shù)量為 1，說明是最后一個被喚醒的 goroutine。
            if !starving || old>>mutexWaiterShift == 1 {
               // 退出饑餓模式
               delta -= mutexStarving
            }
            // 原子操作，設置新狀態(tài)。
            atomic.AddInt32(&m.state, delta)
            break
         }
         // 設置喚醒標記，重新?lián)屨兼i（會與那些運行中的 goroutine 一起競爭鎖）
         awoke = true
         iter = 0
      } else {
         // CAS 更新狀態(tài)失敗，獲取最新狀態(tài)，然后重試
         old = m.state
      }
   }
}

// Unlock 釋放互斥鎖。
// 如果 m 在進入 Unlock 時未被鎖定，則會出現(xiàn)運行時錯誤。
func (m *Mutex) Unlock() {
   // Fast path: drop lock bit.
   // unlock 成功
   // unLock 操作實際上是將 state 減去 1。
   new := atomic.AddInt32(&m.state, -mutexLocked)
   if new != 0 { // 等待隊列為空的時候直接返回了
      // 喚醒一個等待鎖的 goroutine
      m.unlockSlow(new)
   }
}

// unlockSlow 喚醒下一個等待鎖的協(xié)程。
func (m *Mutex) unlockSlow(new int32) {
   // 如果未加鎖，則會拋出錯誤。
   if (new+mutexLocked)&mutexLocked == 0 {
      fatal("sync: unlock of unlocked mutex")
   }

   // 下面的操作是喚醒一個在等待鎖的協(xié)程。
   // 存在兩種情況：
   // 1. 正常模式：
   //  a. 不需要喚醒：沒有等待者、鎖已經(jīng)被搶占、有其他運行中的協(xié)程在嘗試獲取鎖、已經(jīng)進入了饑餓模式
   //   b. 需要喚醒：其他情況
   // 2. 饑餓模式：喚醒等待隊列頭部的那個協(xié)程
   if new&mutexStarving == 0 {
      // 不是饑餓模式
      old := new
      // 自旋
      for {
         // 下面幾種情況不需要喚醒：
         // 1. 沒有等待者了（沒得喚醒）
         // 2. 鎖已經(jīng)被占用（只能有一個 goroutine 持有鎖）
         // 3. 有其他運行中的協(xié)程已經(jīng)被喚醒（運行中的 goroutine 通過自旋先搶占到了鎖）
         // 4. 饑餓模式（饑餓模式下，所有新的 goroutine 都要排隊，饑餓模式會直接喚醒等待隊列頭部的 gorutine）
         if old>>mutexWaiterShift == 0 || old&(mutexLocked|mutexWoken|mutexStarving) != 0 {
            return
         }
         // 獲取到喚醒等待者的權力，開始喚醒一個等待者。
         // 下面這一行實際上是兩個操作：
         // 1. waiter 數(shù)量 - 1
         // 2. 設置 mutexWoken 標志
         new = (old - 1<<mutexWaiterShift) | mutexWoken
         if atomic.CompareAndSwapInt32(&m.state, old, new) {
            // 正常模式下喚醒了一個 goroutine
            //（第二個參數(shù)為 false，表示當前的 goroutine 在釋放信號量后還會繼續(xù)執(zhí)行直到用完時間片）
            runtime_Semrelease(&m.sema, false, 1)
            return
         }
         // 喚醒失敗，進行下一次嘗試。
         old = m.state
      }
   } else {
      // 饑餓模式：將互斥鎖的所有權移交給下一個等待者，并放棄我們的時間片，以便下一個等待者可以立即開始運行。
      // 注意：如果“mutexLocked”未設置，等待者在喚醒后會將其設置。
      // 但是，如果設置了“mutexStarving”，則仍然認為互斥鎖已被鎖定，因此新到來的goroutine不會獲取它。
      //
      // 當前的 goroutine 放棄 CPU 時間片，讓給阻塞在 sema 的 goroutine。
      runtime_Semrelease(&m.sema, true, 1)
   }
}