// AddInt32 atomically adds delta to *addr and returns the new value.
func AddInt32(addr *int32, delta int32) (new int32)

// A Mutex is a mutual exclusion lock.
//
// See package [sync.Mutex] documentation.
type Mutex struct {
	state int32
	sema  uint32
}

// Asynchronous semaphore for sync.Mutex.

// A semaRoot holds a balanced tree of sudog with distinct addresses (s.elem).
// Each of those sudog may in turn point (through s.waitlink) to a list
// of other sudogs waiting on the same address.
// The operations on the inner lists of sudogs with the same address
// are all O(1). The scanning of the top-level semaRoot list is O(log n),
// where n is the number of distinct addresses with goroutines blocked
// on them that hash to the given semaRoot.
// See golang.org/issue/17953 for a program that worked badly
// before we introduced the second level of list, and
// BenchmarkSemTable/OneAddrCollision/* for a benchmark that exercises this.
type semaRoot struct {
    lock  mutex          // 保护整个数据结构的锁
    treap *sudog         // Treap 的根节点
    nwait atomic.Uint32  // 等待者数量（可无锁读取，用于快速判断）
}

// 简单理解：Runtime 内部专用锁
// 通过一个 uintptr 字段同时存储状态标志位和等待 M 线程的指针栈（低 10 位是状态，高位是 M 链表头），
// 直接用 OS 信号量阻塞 M 线程，禁用抢占，零分配，不触发 GC。
type mutex struct {
	lockRankStruct
	key uintptr
}

// sudog (pseudo-g) 代表的是一个在等待队列中的 goroutine
type sudog struct {
    g *g                // 指向等待的 goroutine

    // === Treap 二叉树指针 ===
    parent *sudog       // 父节点
    prev   *sudog       // 左子节点
    next   *sudog       // 右子节点

    // === 同地址等待链表 ===
    waitlink *sudog     // 链表中的下一个等待者
    waittail *sudog     // 链表尾部（只在头节点有效）

    // === 地址和优先级 ===
    elem   unsafe.Pointer  // 等待的地址（如 &mutex.sema）
    ticket uint32          // Treap 的堆优先级（随机数）

    // === 统计和性能分析 ===
    waiters     uint16  // 链表中其他等待者的数量（头节点）
    acquiretime int64   // 开始等待的时间
    releasetime int64   // 被唤醒的时间
}

func semacquire1(addr *uint32, lifo bool, profile semaProfileFlags, skipframes int, reason waitReason) {
	gp := getg()
	if gp != gp.m.curg {
		throw("semacquire not on the G stack")
	}

	// 快捷路径，先进行一次简单的原子操作尝试获取锁，成功则直接返回
	if cansemacquire(addr) {
		return
	}

  // 慢速路径：
	// Harder case:
	//	increment waiter count
	//	try cansemacquire one more time, return if succeeded
	//	enqueue itself as a waiter
	//	sleep
	//	(waiter descriptor is dequeued by signaler)
  // 获取 sema 底层的 semaRoot，并为它赋初始值
	s := acquireSudog()
	root := semtable.rootFor(addr)
	for {
		lockWithRank(&root.lock, lockRankRoot)
		// 1. 自增等待者数量
		root.nwait.Add(1)
		// 2. 再次尝试获取锁，成功则可以返回了
		if cansemacquire(addr) {
			root.nwait.Add(-1)
			unlock(&root.lock)
			break
		}
    // 3. 还是失败，则进入休眠队列
		root.queue(addr, s, lifo)
    // 4. 调用 gopark() 休眠协程（不了解 gopark 可以先去了解一下 GMP 底层原理）
		goparkunlock(&root.lock, reason, traceBlockSync, 4+skipframes)
		if s.ticket != 0 || cansemacquire(addr) {
			break
		}
	}
	if s.releasetime > 0 {
		blockevent(s.releasetime-t0, 3+skipframes)
	}
	releaseSudog(s)
}

// 判断是否可以获取 sema 锁
func cansemacquire(addr *uint32) bool {
	for {
		v := atomic.Load(addr)
    // sema 为 0，表示没锁了，这个时候是一个等待队列，无法直接获取锁
		if v == 0 {
			return false
		}
    // sema 大于 0，说明这个时候有可以并发的协程个数，尝试进行 cas 获取锁，成功则返回 true
		if atomic.Cas(addr, v, v-1) {
			return true
		}
	}
}

// semrelease1 释放一个信号量，如果有等待者则唤醒一个 goroutine
// addr: 信号量地址（如 &mutex.sema）
// handoff: 是否直接移交（饥饿模式下为 true，直接把锁交给被唤醒者）
// skipframes: 用于性能分析时跳过的栈帧数
func semrelease1(addr *uint32, handoff bool, skipframes int) {
	// 通过 addr 的哈希值找到对应的 semaRoot
	root := semtable.rootFor(addr)

	// ===== 关键操作：先递增信号量计数器 =====
	// 无论有没有等待者，都原子地将 *addr 加 1
	// 这相当于传统信号量的 V 操作，释放一个"资源"
	atomic.Xadd(addr, 1)

	// ===== Fast Path：快速检查是否有等待者 =====
	//
	// 注意顺序很重要！必须先执行 Xadd，再检查 nwait
	// 原因：防止 "错过唤醒" 的竞态条件
	// - semacquire 的顺序是：先 nwait++，再 cansemacquire，最后 gopark
	// - 如果我们先检查 nwait 再 Xadd，可能在两步之间 semacquire 刚好 nwait++
	//   导致我们误以为没有等待者而不唤醒，但 goroutine 已经睡眠了
	if root.nwait.Load() == 0 {
		return  // 没有等待者，直接返回（信号量值已经被递增了）
	}

	// ===== Slow Path：有等待者，需要唤醒一个 =====
  //
	// 获取 semaRoot 的锁，保护等待队列的并发访问
	lockWithRank(&root.lock, lockRankRoot)

	// 持锁后再次检查 nwait，因为可能在获取锁之前已经被其他人消费了
	if root.nwait.Load() == 0 {
		// 场景：我们在获取锁期间，另一个 goroutine 可能：
		// 1. 调用了 semacquire 并通过 cansemacquire 成功获取（消费了我们递增的值）
		// 2. 减少了 nwait 计数
		// 所以不需要再唤醒任何人了
		unlock(&root.lock)
		return
	}

	// 从等待队列中取出一个等待者（sudog）
	// s: 要唤醒的 sudog
	// t0: 当前时间（用于性能统计）
	// tailtime: 队尾等待者的开始等待时间（用于计算平均等待时间）
	s, t0, tailtime := root.dequeue(addr)

	if s != nil {
		// 成功取出一个等待者，减少等待者计数
		root.nwait.Add(-1)
	}

	// 尽快释放锁，因为后续操作可能很慢（甚至可能让出 CPU）
	unlock(&root.lock)
	if s != nil {
		// ===== Handoff 模式：直接移交锁 =====
		if handoff && cansemacquire(addr) {
			// handoff=true 表示饥饿模式
			// 尝试提前消费信号量（将 *addr 减 1）
			// 如果成功，设置 ticket=1，告诉被唤醒的 goroutine：
			// "你不需要竞争了，锁已经是你的了"
			s.ticket = 1
		}

		// ===== 唤醒 goroutine =====
		// 将 sudog 对应的 goroutine 标记为可运行
		// 并将其加入到当前 P 的 runnext 位置（优先运行）
		readyWithTime(s, 5+skipframes)

		// ===== Direct G Handoff：直接切换到被唤醒者 =====
		if s.ticket == 1 && getg().m.locks == 0 && getg() != getg().m.g0 {
			// 条件满足时，主动让出 CPU 给被唤醒者立即运行：
			// - s.ticket == 1：已经直接移交了锁
			// - getg().m.locks == 0：当前没有持有其他 runtime 锁
			// - getg() != getg().m.g0：不在系统栈上
			//
			// readyWithTime 已经把被唤醒者放到了 P 的 runnext 位置
			// 现在调用 goyield() 主动让出时间片：
			// - 被唤醒者继承我们的时间片，立即开始运行
			// - 避免高竞争场景下某个 goroutine 霸占 P
			// - goyield 会把当前 G 放到本地队列（不是全局队列）
			//
			// 只在饥饿模式（handoff=true）下这样做，因为：
			// - 正常模式：被唤醒者可能竞争失败，让出 CPU 会浪费
			// - 饥饿模式：已经直接移交，保证能获取锁，不会浪费
			//
			// 相关讨论见 issue 33747
			goyield()
		}
	}
}

type Mutex struct {
    state int32
    sema  uint32 // <--- 就是它
}

var semtable semTable

// Prime to not correlate with any user patterns.
const semTabSize = 251

type semTable [semTabSize]struct {
	root semaRoot
	pad  [cpu.CacheLinePadSize - unsafe.Sizeof(semaRoot{})]byte
}

func (t *semTable) rootFor(addr *uint32) *semaRoot {
	return &t[(uintptr(unsafe.Pointer(addr))>>3)%semTabSize].root
}

type Mutex struct {
	state int32
	sema  uint32
}

// 初始状态
state = 0b00000000_00000000_00000000_00000000

// goroutine A 获取锁
state = 0b00000000_00000000_00000000_00000001  // L=1

// goroutine B 尝试获取，进入等待队列
state = 0b00000000_00000000_00000000_00001001  // L=1, waiter=1

// goroutine B 设置了 woken 标志（自旋中）
state = 0b00000000_00000000_00000000_00001011  // L=1, W=1, waiter=1

// 等待超过 1ms，进入饥饿模式
state = 0b00000000_00000000_00000000_00001101  // L=1, S=1, waiter=1

func (m *Mutex) lockSlow() {
	// ===== 初始化局部变量 =====
	var waitStartTime int64  // 开始等待的时间戳（用于判断是否饥饿）
	starving := false        // 当前 goroutine 是否处于饥饿状态
	awoke := false           // 当前 goroutine 是否从休眠中被唤醒
	iter := 0                // 自旋迭代次数
	old := m.state           // 保存当前 mutex 的状态

	// ===== 主循环：不断尝试获取锁 =====
	for {
		// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		// 第一阶段：自旋尝试（Active Spinning）
		// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		// 自旋条件：
		// 1. old&mutexLocked != 0：锁已被持有
		// 2. old&mutexStarving == 0：不在饥饿模式（饥饿模式下新来的不能竞争）
		// 3. runtime_canSpin(iter)：满足自旋条件（多核、迭代次数 < 4、有其他 P 等）
		if old&(mutexLocked|mutexStarving) == mutexLocked && runtime_canSpin(iter) {
			// 尝试设置 mutexWoken 标志，条件：
			// 1. !awoke：我们还没设置过
			// 2. old&mutexWoken == 0：当前没有其他 goroutine 设置
			// 3. old>>mutexWaiterShift != 0：有等待者（不然设置 woken 没意义）
			//
			// 目的：告诉 Unlock "有人在自旋，不要唤醒休眠的 goroutine"，减少不必要的唤醒开销
			if !awoke && old&mutexWoken == 0 && old>>mutexWaiterShift != 0 &&
				atomic.CompareAndSwapInt32(&m.state, old, old|mutexWoken) {
				awoke = true
			}

			// 执行实际的自旋（CPU 级别的忙等待）
			runtime_doSpin()
			iter++
			old = m.state  // 重新读取状态
			continue       // 继续下一轮尝试
		}

		// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		// 第二阶段：准备新的状态值（CAS 更新）
		// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		new := old  // 基于旧状态构造新状态

		// 如果不在饥饿模式，尝试设置 mutexLocked 位
		// （在饥饿模式下，新来的 goroutine 不能直接抢锁，必须排队）
		if old&mutexStarving == 0 {
			new |= mutexLocked
		}

		// 如果锁已被持有或处于饥饿模式，增加等待者计数（即将进入等待队列）
		if old&(mutexLocked|mutexStarving) != 0 {
			new += 1 << mutexWaiterShift  // 等待者数量 +1
		}

		// 如果当前 goroutine 已经饥饿（等待超过 1ms），并且锁还被持有
		// 则尝试将 mutex 切换到饥饿模式
		// 注意：只在锁被持有时切换，因为 Unlock 期望饥饿模式必有等待者
		if starving && old&mutexLocked != 0 {
			new |= mutexStarving
		}

		// 如果当前 goroutine 是被唤醒的，需要清除 mutexWoken 标志
		if awoke {
			// 清除 mutexWoken 标志（用 &^ 位清除操作）
			new &^= mutexWoken
		}

		// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
		// 第三阶段：CAS 更新状态
		// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

		// 尝试用 CAS 将状态从 old 更新为 new
		if atomic.CompareAndSwapInt32(&m.state, old, new) {
			// CAS 成功！

			// 检查是否成功获取了锁
			// 条件：旧状态既没锁定也不在饥饿模式
			if old&(mutexLocked|mutexStarving) == 0 {
				break // 成功获取锁，退出循环！
			}

			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
			// 第四阶段：进入等待队列并休眠
			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

			// 如果之前已经等待过（被唤醒后重新竞争失败），插入队首（LIFO）
			// 否则插入队尾（FIFO）
			queueLifo := waitStartTime != 0

			// 记录开始等待的时间（只记录一次）
			if waitStartTime == 0 {
				waitStartTime = runtime_nanotime()
			}

      // 调用 semacuqire 进入休眠 <--- 阻塞在这里，直到被唤醒
			runtime_SemacquireMutex(&m.sema, queueLifo, 2)

			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
			// 被唤醒了！从这里继续执行
			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

			// 检查是否应该进入饥饿模式
			// 条件：之前已经饥饿 || 等待时间超过 1ms
			starving = starving || runtime_nanotime()-waitStartTime > starvationThresholdNs

			// 重新读取当前状态
			old = m.state

			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
			// 饥饿模式的特殊处理
			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

			if old&mutexStarving != 0 {
				// 饥饿模式下被唤醒，说明锁被直接移交给我们了
				// 但此时状态还不一致：
				// - mutexLocked 还没设置（需要我们设置）
				// - 我们还被计入等待者（需要减 1）


				// 计算状态变化：
				// +mutexLocked：设置锁定标志
				// -1<<mutexWaiterShift：等待者数量减 1
				delta := int32(mutexLocked - 1<<mutexWaiterShift)

				// 决定是否退出饥饿模式
				// 条件：
				// 1. 当前 goroutine 不再饥饿（等待时间 < 1ms）
				// 2. 或者我们是最后一个等待者
				if !starving || old>>mutexWaiterShift == 1 {
					// 退出饥饿模式（清除 mutexStarving 标志）
					// 注意：必须在这里退出，考虑实际等待时间
					// 饥饿模式效率低，如果不及时退出，两个 goroutine
					// 可能会无限期地在饥饿模式下来回切换
					delta -= mutexStarving
				}

				// 原子更新状态
				atomic.AddInt32(&m.state, delta)
				break  // 成功获取锁，退出循环！
			}

			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
			// 正常模式被唤醒：重新开始竞争
			// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

			awoke = true   // 标记为已唤醒
			iter = 0       // 重置自旋计数器（可以重新自旋）

		} else {
			// CAS 失败：状态被其他 goroutine 改变了
			// 重新读取状态，继续下一轮循环
			old = m.state
		}
	}
	// ===== 成功获取锁，退出循环 =====
}

const (
	active_spin     = 4  // referenced in proc.go for sync.Mutex implementation
	active_spin_cnt = 30 // referenced in proc.go for sync.Mutex implementation
)

func internal_sync_runtime_canSpin(i int) bool {
  // 必须同时满足：
	// 	- 自旋次数 < 4
	// 	- 多核 CPU（numCPU > 1）
	//  - 有其他运行的 P
  //  - 本地运行队列为空
	if i >= active_spin || numCPUStartup <= 1 || gomaxprocs <= sched.npidle.Load()+sched.nmspinning.Load()+1 {
		return false
	}
	if p := getg().m.p.ptr(); !runqempty(p) {
		return false
	}
	return true
}

func (m *Mutex) Unlock() {
	// ===== Fast Path：快速路径（无竞争情况）=====
	// 原子地将 state 减去 mutexLocked（即清除锁定标志位）
	// 如果 mutex 完全空闲（无等待者、无其他标志），new 将等于 0
  // 如果 new == 0，说明没有等待者，直接返回（最快路径）
	new := atomic.AddInt32(&m.state, -mutexLocked)
	if new != 0 {
		// new != 0 说明还有其他信息（等待者、标志位等）
		// 需要进入慢速路径处理
		m.unlockSlow(new)
	}
}

// unlockSlow 是 Unlock 的慢速路径，处理有等待者或特殊标志的情况
// 参数 new：已经减去 mutexLocked 后的新状态值
func (m *Mutex) unlockSlow(new int32) {
	// 不允许对未加锁的 mutex 进行 unlock!
	if (new+mutexLocked)&mutexLocked == 0 {
		fatal("sync: unlock of unlocked mutex")
	}

	// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
	// 分支 1：正常模式（Normal Mode）
	// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
	if new&mutexStarving == 0 {
		// 正常模式下的唤醒逻辑：不保证被唤醒者一定能获取锁
		old := new

		for {
			// ===== 检查是否需要唤醒等待者 =====
			// 以下任一条件满足，都无需唤醒：
			// 1. old>>mutexWaiterShift == 0
			//    → 没有等待者
			//
			// 2. old&mutexLocked != 0
			//    → 锁已经被其他 goroutine 抢走了
			//       （在我们 Unlock 之后，有新来的 goroutine 直接 CAS 获取了锁）
			//
			// 3. old&mutexWoken != 0
			//    → 已经有一个 goroutine 被标记为唤醒状态
			//       （可能在自旋，或者已经被其他 Unlock 唤醒）
			//
			// 4. old&mutexStarving != 0
			//    → 进入饥饿模式了
			//       （虽然我们检查的是 new&mutexStarving == 0 才进这个分支，
			//        但在循环中 old 可能被其他 goroutine 更新了）
			//       饥饿模式有专门的处理逻辑，我们不应该干预
			if old>>mutexWaiterShift == 0 || old&(mutexLocked|mutexWoken|mutexStarving) != 0 {
				return  // 不需要唤醒，直接返回
			}

			// ===== 准备唤醒一个等待者 =====

			// 构造新状态：
			// 1. old - 1<<mutexWaiterShift：等待者数量减 1
			// 2. | mutexWoken：设置 mutexWoken 标志
			//
			// mutexWoken 的作用：
			// - 告诉正在 Lock 的 goroutine："已经有人被唤醒了"
			// - 避免多个 Unlock 重复唤醒
			// - 被唤醒的 goroutine 会清除这个标志
			new = (old - 1<<mutexWaiterShift) | mutexWoken

			// 用 CAS 更新状态
			if atomic.CompareAndSwapInt32(&m.state, old, new) {
				// CAS 成功！我们获得了唤醒的权利

				// 调用 runtime 的信号量释放操作，唤醒一个等待者
				// 参数：
				// - &m.sema：信号量地址
				// - false：handoff=false，正常模式，不直接移交
				//          被唤醒的 goroutine 需要重新竞争锁
				// - 2：skipframes（用于性能分析）
				runtime_Semrelease(&m.sema, false, 2)
				return
			}

			// CAS 失败：状态被其他 goroutine 改变了
			// 重新读取状态，继续下一轮循环
			old = m.state
		}

	// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
	// 分支 2：饥饿模式（Starvation Mode）
	// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
	} else {
		// 饥饿模式的特殊处理：
		//
		// 1. 直接移交所有权（handoff=true）
		//    - 被唤醒的 goroutine 保证能获取锁
		//    - 不需要重新竞争
		//
		// 2. mutexLocked 位不设置
		//    - 被唤醒的 goroutine 会自己设置
		//    - 见 lockSlow 中 old&mutexStarving != 0 分支
		//
		// 3. mutexStarving 标志保持
		//    - 新来的 goroutine 看到这个标志，知道不能竞争
		//    - 必须排队等待
		//
		// 4. 当前 goroutine 会主动让出 CPU（在 semrelease1 中 goyield）
		//    - 让被唤醒者立即运行
		//    - 避免延迟

    // 调用 semarelease() 释放操作
		// 参数：
		// - &m.sema：信号量地址
		// - true：handoff=true，饥饿模式，直接移交
		//         semrelease1 会设置 ticket=1，并调用 goyield()
		// - 2：skipframes（用于性能分析）
		runtime_Semrelease(&m.sema, true, 2)
	}
}

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 atomic.Int32 // number of pending readers
	readerWait  atomic.Int32 // number of departing readers
}

const rwmutexMaxReaders = 1 << 30 // 最多的读者个数，是一个非常大的值

func (rw *RWMutex) Lock() {
	// 1. 抢占获取写锁的资格
	rw.w.Lock()
	// Announce to readers there is a pending writer.
  // 2. 原子变量 readerCount 减去 rwmutexMaxReaders 表明当前有写的需求，
  // 	阻止后续读锁的抢占，写者优先！
  // 	再加回去是要恢复原来的值，以得到抢锁之前正常读的协程的个数 r
	r := rw.readerCount.Add(-rwmutexMaxReaders) + rwmutexMaxReaders
  // 3. 陷入 writerSem，等待 readerWait 个正在读的协程释放读锁
	if r != 0 && rw.readerWait.Add(r) != 0 {
		runtime_SemacquireRWMutex(&rw.writerSem, false, 0)
	}
  // 4. 抢锁成功
}

func (rw *RWMutex) Unlock() {
  // 1. 把 rwmutexMaxReaders 加回去，表示已经没有写协程了
	r := rw.readerCount.Add(rwmutexMaxReaders)
	if r >= rwmutexMaxReaders {
    // 不允许对未上锁的锁进行 Unlock！
		fatal("sync: Unlock of unlocked RWMutex")
	}
  // 2. 唤醒所有阻塞在 readerSem 中的读协程
	for i := 0; i < int(r); i++ {
		runtime_Semrelease(&rw.readerSem, false, 0)
	}
	// 3. 允许其他协程抢占写锁
	rw.w.Unlock()
}

func (rw *RWMutex) RLock() {
  // 1. readerCount++，检查是否有写锁
	if rw.readerCount.Add(1) < 0 {
		// 2. 有写锁，则陷入 readerSem，等待写锁释放
		runtime_SemacquireRWMutexR(&rw.readerSem, false, 0)
	}
  // 3. 没有写锁或者写锁释放后唤醒 readerSem，则获得读锁成功
}

func (rw *RWMutex) RUnlock() {
  // 1. 释放当前读锁，将 readerCount --
  // 2. 检查是否有写协程正在等待
	if r := rw.readerCount.Add(-1); r < 0 {
		// 3. 如果有写协程等待，则往下走
		rw.rUnlockSlow(r)
	}
}

func (rw *RWMutex) rUnlockSlow(r int32) {
	if r+1 == 0 || r+1 == -rwmutexMaxReaders {
		fatal("sync: RUnlock of unlocked RWMutex")
	}
  // 4. readerWait--
  // 5. 判断是否是最后一个释放读锁的协程
	if rw.readerWait.Add(-1) == 0 {
		// 6. 是的话，就从 writerSem 中唤醒写协程
		runtime_Semrelease(&rw.writerSem, false, 1)
	}
}

type WaitGroup struct {
	noCopy noCopy   // 防止拷贝

	// Bits (high to low):
	//   bits[0:32]  counter
	//   bits[32]    flag: synctest bubble membership
	//   bits[33:64] wait count
	state atomic.Uint64  // 核心状态字段（64位）
	sema  uint32				 // sema 锁地址
}

state := wg.state.Load()
counter := int32(state >> 32)     // 取高32位
waiter := uint32(state & 0x7fffffff) // 取低31位（忽略bubble flag）

func (wg *WaitGroup) Wait() {
    for {
        state := wg.state.Load()
        v := int32(state >> 32)    // counter

        // 1. Fast Path: counter == 0，直接返回
        if v == 0 {
            return
        }

        // 2. Slow Path: counter > 0，需要等待
        // 用 CAS 增加 waiter 计数
        if wg.state.CompareAndSwap(state, state+1) {
            // CAS 成功，进入等待
            runtime_SemacquireWaitGroup(&wg.sema, false)
            // 被唤醒后返回
            return
        }
        // CAS 失败，重试
    }
}

func (wg *WaitGroup) Add(delta int) {
    // 1. 原子地将 delta 加到 counter（高32位）
    state := wg.state.Add(uint64(delta) << 32)

    // 2. 解析 state
    v := int32(state >> 32)  // counter
    w := uint32(state & 0x7fffffff) // waiter count

    // 3. 错误检查
    if v < 0 {
        panic("negative counter")
    }
    if w != 0 && delta > 0 && v == int32(delta) {
        panic("Add called concurrently with Wait")
    }

    // 4. 快速返回：counter > 0 或没有 waiter
    if v > 0 || w == 0 {
        return
    }

    // 5. 关键时刻：counter 降到 0，且有 waiter 在等待
    //    → 唤醒所有 waiter！
    wg.state.Store(0)  // 重置状态
    for ; w != 0; w-- {
        runtime_Semrelease(&wg.sema, false, 0)  // 唤醒一个
    }
}

func (wg *WaitGroup) Done() {
  // 就是执行 counnter--
	wg.Add(-1)
}

type Once struct {
	_ noCopy

	done atomic.Bool
	m    Mutex
}

func (o *Once) Do(f func()) {
  // 如果已经执行过的了，直接返回
	if !o.done.Load() {
		o.doSlow(f)
	}
}

func (o *Once) doSlow(f func()) {
  // 上锁
	o.m.Lock()
	defer o.m.Unlock()
  // 上锁后二次检查
	if !o.done.Load() {
		defer o.done.Store(true)
		f()
	}
}

c.L.Lock()          // 1. 先加锁（保护条件 condition）
for !condition() {  // 2. 必须用 for 循环检查（防止虚假唤醒）
    c.Wait()        // 3. 挂起（内部会：解锁 -> 睡 -> 加锁）
}
// 执行业务逻辑...
c.L.Unlock()        // 4. 最终解锁

type Cond struct {
    noCopy  noCopy       // 防止拷贝
    L       Locker       // 关联的锁（通常是 *Mutex 或 *RWMutex）
    notify  notifyList   // 等待队列（ticket-based）
    checker copyChecker  // 运行时拷贝检测
}

type notifyList struct {
	wait atomic.Uint32 // 下一个等待者的票号（原子递增）
	notify uint32 // 下一个要通知的票号

	// 等待者列表
	lock mutex
	head *sudog
	tail *sudog
}

func (c *Cond) Wait() {
    // 步骤 1: 拿号 (Ticket Allocation)
    // 关键点：在解锁之前先拿号！
    // 这保证了即使我还没睡着，Signal 发送者也能知道"有一个持有 t 号的人正在赶来的路上"。
    t := runtime_notifyListAdd(&c.notify)

    // 步骤 2: 解锁 (Unlock User Lock)
    // 必须解锁，否则 Signal 的发送者无法获得锁来修改条件，死锁。
    c.L.Unlock()

    // 步骤 3: 入队并休眠 (Enqueue & Park)
    runtime_notifyListWait(&c.notify, t)

    // 步骤 4: 重新加锁 (Relock)
    // 醒来后，必须恢复到调用 Wait 前的状态，以便重新检查 for !condition()。
    c.L.Lock()
}

func notifyListAdd(l *notifyList) uint32 {
	// This may be called concurrently, for example, when called from
	// sync.Cond.Wait while holding a RWMutex in read mode.
	return l.wait.Add(1) - 1
}

func notifyListWait(l *notifyList, t uint32) {
	lockWithRank(&l.lock, lockRankNotifyList)

  // 进入 notifyListWait 后，再次检查一下 l.notify），
  // 如果 l.notify > t，说明已经被叫过了，
  // 那我就不睡了，直接返回。这完美解决了信号丢失问题。
	if less(t, l.notify) {
		unlock(&l.lock)
		return
	}

	// 入队休眠
	s := acquireSudog()
	s.g = getg()
	s.ticket = t
	s.releasetime = 0
	t0 := int64(0)
	if blockprofilerate > 0 {
		t0 = cputicks()
		s.releasetime = -1
	}
	if l.tail == nil {
		l.head = s
	} else {
		l.tail.next = s
	}
	l.tail = s
	goparkunlock(&l.lock, waitReasonSyncCondWait, traceBlockCondWait, 3)
	if t0 != 0 {
		blockevent(s.releasetime-t0, 2)
	}
	releaseSudog(s)
}

func (c *Cond) Signal() {
	runtime_notifyListNotifyOne(&c.notify)
}

func notifyListNotifyOne(l *notifyList) {
  // 如果 wait == notify，说明没有新的等待者，直接返回
	if l.wait.Load() == atomic.Load(&l.notify) {
		return
	}

  // 获取锁，因为需要修改 notifylist
	lockWithRank(&l.lock, lockRankNotifyList)

	// 双重检查，如果没有新的等待者，则直接返回
	t := l.notify
	if t == l.wait.Load() {
		unlock(&l.lock)
		return
	}

	// 更新下一个 notify 的票号
	atomic.Store(&l.notify, t+1)

	// 从 notifyList 尝试唤醒一个休眠中的 G
	for p, s := (*sudog)(nil), l.head; s != nil; p, s = s, s.next {
		if s.ticket == t {
			n := s.next
			if p != nil {
				p.next = n
			} else {
				l.head = n
			}
			if n == nil {
				l.tail = p
			}
			unlock(&l.lock)
			s.next = nil
			if s.g.bubble != nil && getg().bubble != s.g.bubble {
				println("semaphore wake of synctest goroutine", s.g.goid, "from outside bubble")
				fatal("semaphore wake of synctest goroutine from outside bubble")
			}
      // 唤醒
			readyWithTime(s, 4)
			return
		}
	}
	unlock(&l.lock)
}

func readyWithTime(s *sudog, traceskip int) {
	if s.releasetime != 0 {
		s.releasetime = cputicks()
	}
	goready(s.g, traceskip)
}

func (c *Cond) Broadcast() {
	runtime_notifyListNotifyAll(&c.notify)
}

func notifyListNotifyAll(l *notifyList) {
	// 没有新的等待者，直接返回
	if l.wait.Load() == atomic.Load(&l.notify) {
		return
	}

	// 上锁
	lockWithRank(&l.lock, lockRankNotifyList)
  // 清空 notifyList，因为全部都会被唤醒
	s := l.head
	l.head = nil
	l.tail = nil

	// 更新 notify 为当前的 wait
	atomic.Store(&l.notify, l.wait.Load())
	unlock(&l.lock)

	// 唤醒旧的 notifyList 的所有 sudog
	for s != nil {
		next := s.next
		s.next = nil
		if s.g.bubble != nil && getg().bubble != s.g.bubble {
			println("semaphore wake of synctest goroutine", s.g.goid, "from outside bubble")
			fatal("semaphore wake of synctest goroutine from outside bubble")
		}
    // 唤醒
		readyWithTime(s, 4)
		s = next
	}
}

m := sync.Mutex{}
m.Lock()
n := m // n 拷贝 m
m.Unlock()
n.Lock()  // 这里会报错，因为 n 在拷贝 m 的时候，把它已经 lock 的状态也拷贝了

// 此处 i 有并发问题
func add(i *int32) {
	*i++
}

func main() {
	c := int32(0)
	for i := 0; i < 100; i++ {
		go add(&c)
	}
	time.Sleep(time.Second)
}