type Weighted
    func NewWeighted(n int64) *Weighted
    func (s *Weighted) Acquire(ctx context.Context, n int64) error
    func (s *Weighted) Release(n int64)
    func (s *Weighted) TryAcquire(n int64) bool

// Weighted 信號量結構體
type Weighted struct {
	size    int64      // 資源總數(shù)量
	cur     int64      // 當前已經(jīng)使用的資源數(shù)
	mu      sync.Mutex // 互斥鎖，保證對其他屬性的操作并發(fā)安全
	waiters list.List  // 等待者隊列，使用列表實現(xiàn)
}

// NewWeighted 構造一個信號量對象
func NewWeighted(n int64) *Weighted {
	w := &Weighted{size: n}
	return w
}

// 等待者結構體
type waiter struct {
	n     int64           // 請求資源數(shù)
	ready chan<- struct{} // 當獲取到資源時被關閉，用于喚醒當前等待者
}

// Acquire 請求 n 個資源
// 如果資源不足，則阻塞等待，直到有足夠的資源數(shù)，或者 ctx 被取消
// 成功返回 nil，失敗返回 ctx.Err() 并且不改變資源數(shù)
func (s *Weighted) Acquire(ctx context.Context, n int64) error {
	done := ctx.Done()

	s.mu.Lock() // 加鎖保證并發(fā)安全

	// 如果在分配資源前 ctx 已經(jīng)取消，則直接返回 ctx.Err()
	select {
	case <-done:
		s.mu.Unlock()
		return ctx.Err()
	default:
	}

	// 如果資源數(shù)足夠，且不存在其他等待者，則請求資源成功，將 cur 加上 n，并返回
	if s.size-s.cur >= n && s.waiters.Len() == 0 {
		s.cur += n
		s.mu.Unlock()
		return nil
	}

	// 如果請求的資源數(shù)大于資源總數(shù)，不可能滿足，則阻塞等待 ctx 取消，并返回 ctx.Err()
	if n > s.size {
		// Don't make other Acquire calls block on one that's doomed to fail.
		s.mu.Unlock()
		<-done
		return ctx.Err()
	}

	// 資源不夠或者存在其他等待者，則繼續(xù)執(zhí)行

	// 加入等待隊列
	ready := make(chan struct{})    // 創(chuàng)建一個 channel 作為一個屬性記錄到等待者對象 waiter 中，用于后續(xù)通知其喚醒
	w := waiter{n: n, ready: ready} // 構造一個等待者對象 waiter
	elem := s.waiters.PushBack(w)   // 將 waiter 追加到等待者隊列
	s.mu.Unlock()

	// 使用 select 實現(xiàn)阻塞等待
	select {
	case <-done: // 檢查 ctx 是否被取消
		s.mu.Lock()
		select {
		case <-ready: // 檢查當前 waiter 是否被喚醒
			// 進入這里，說明是 ctx 被取消后 waiter 被喚醒
			s.cur -= n        // 那么就當作 waiter 沒有被喚醒，將請求的資源數(shù)還回去
			s.notifyWaiters() // 通知等待隊列，檢查隊列中下一個 waiter 資源數(shù)是否滿足
		default: // 將當前 waiter 從等待者隊列中移除
			isFront := s.waiters.Front() == elem // 當前 waiter 是否為第一個等待者
			s.waiters.Remove(elem)               // 從隊列中移除
			// 如果當前 waiter 是隊列中第一個等待者，并且還有剩余的資源數(shù)
			if isFront && s.size > s.cur {
				s.notifyWaiters() // 通知等待隊列，檢查隊列中下一個 waiter 資源數(shù)是否滿足
			}
		}
		s.mu.Unlock()
		return ctx.Err()

	case <-ready: // 被喚醒
		select {
		case <-done: // 再次檢查 ctx 是否被取消
			// 進入這里，說明 waiter 被喚醒后 ctx 卻被取消了，當作未被喚醒來處理
			s.Release(n) // 釋放資源
			return ctx.Err()
		default:
		}
		return nil // 成功返回 nil
	}
}

// Release 釋放 n 個資源
func (s *Weighted) Release(n int64) {
	s.mu.Lock() // 加鎖保證并發(fā)安全
	s.cur -= n  // 釋放資源
	if s.cur < 0 {
		s.mu.Unlock()
		panic("semaphore: released more than held")
	}
	s.notifyWaiters() // 通知等待隊列，檢查隊列中下一個 waiter 資源數(shù)是否滿足
	s.mu.Unlock()
}

// 檢查隊列中下一個 waiter 資源數(shù)是否滿足
func (s *Weighted) notifyWaiters() {
	// 循環(huán)檢查下一個 waiter 請求的資源數(shù)是否滿足，滿足則出隊，不滿足則終止循環(huán)
	for {
		next := s.waiters.Front() // 獲取隊首元素
		if next == nil {
			break // 沒有 waiter 了，隊列為空終止循環(huán)
		}

		w := next.Value.(waiter)
		if s.size-s.cur < w.n { // 當前 waiter 資源數(shù)不滿足，退出循環(huán)
			// 不繼續(xù)查找隊列中后續(xù) waiter 請求資源是否滿足，避免產(chǎn)生饑餓
			break
		}

		// 資源數(shù)滿足，喚醒 waiter
		s.cur += w.n           // 記錄使用的資源數(shù)
		s.waiters.Remove(next) // 從隊列中移除 waiter
		close(w.ready)         // 利用關閉 channel 的操作，來喚醒 waiter
	}
}

// TryAcquire 嘗試請求 n 個資源
// 不阻塞，成功返回 true，失敗返回 false 并且不改變資源數(shù)
func (s *Weighted) TryAcquire(n int64) bool {
	s.mu.Lock() // 加鎖保證并發(fā)安全
	// 剩余資源數(shù)足夠，且不存在其他等待者，則請求資源成功
	success := s.size-s.cur >= n && s.waiters.Len() == 0
	if success {
		s.cur += n // 記錄當前已經(jīng)使用的資源數(shù)
	}
	s.mu.Unlock()
	return success
}

package main

import (
	"context"
	"fmt"
	"log"
	"runtime"

	"golang.org/x/sync/semaphore"
)

func main() {
	ctx := context.TODO()

	var (
		maxWorkers = runtime.GOMAXPROCS(0)                    // worker pool 支持的最大 worker 數(shù)量，取當前機器 CPU 核心數(shù)
		sem        = semaphore.NewWeighted(int64(maxWorkers)) // 信號量，資源總數(shù)即為最大 worker 數(shù)量
		out        = make([]int, 32)                          // 總任務數(shù)量
	)

	// 一次最多啟動 maxWorkers 數(shù)量個 goroutine 計算輸出
	for i := range out {
		// 當最大工作數(shù) maxWorkers 個 goroutine 正在執(zhí)行時，Acquire 會阻塞直到其中一個 goroutine 完成
		if err := sem.Acquire(ctx, 1); err != nil { // 請求資源
			log.Printf("Failed to acquire semaphore: %v", err)
			break
		}

		// 開啟新的 goroutine 執(zhí)行計算任務
		go func(i int) {
			defer sem.Release(1)         // 任務執(zhí)行完成后釋放資源
			out[i] = collatzSteps(i + 1) // 執(zhí)行 Collatz 步驟計算
		}(i)
	}

	// 獲取所有的 tokens 以等待全部 goroutine 執(zhí)行完成
	if err := sem.Acquire(ctx, int64(maxWorkers)); err != nil {
		log.Printf("Failed to acquire semaphore: %v", err)
	}

	fmt.Println(out)

}

// collatzSteps computes the number of steps to reach 1 under the Collatz
// conjecture. (See https://en.wikipedia.org/wiki/Collatz_conjecture.)
func collatzSteps(n int) (steps int) {
	if n <= 0 {
		panic("nonpositive input")
	}

	for ; n > 1; steps++ {
		if steps < 0 {
			panic("too many steps")
		}

		if n%2 == 0 {
			n /= 2
			continue
		}

		const maxInt = int(^uint(0) >> 1)
		if n > (maxInt-1)/3 {
			panic("overflow")
		}
		n = 3*n + 1
	}

	return steps
}

func main() {
	var (
		maxWorkers = runtime.GOMAXPROCS(0)           // 獲取系統(tǒng)可用的最大 CPU 核心數(shù)
		out        = make([]int, 32)                 // 存儲 Collatz 結果
		wg         sync.WaitGroup                    // 用于等待 goroutine 完成
		sem        = make(chan struct{}, maxWorkers) // 用于限制最大并發(fā)數(shù)
	)

	for i := range out {
		// 通過 sem 管理并發(fā)，確保最多只有 maxWorkers 個 goroutine 同時執(zhí)行
		sem <- struct{}{} // 如果 sem 已滿，這里會阻塞，直到有空閑槽位

		// 增加 WaitGroup 計數(shù)
		wg.Add(1)

		go func(i int) {
			defer wg.Done()          // goroutine 完成時，減少 WaitGroup 計數(shù)
			defer func() { <-sem }() // goroutine 完成時，從 sem 中釋放一個槽位

			// 執(zhí)行 Collatz 步驟計算
			out[i] = collatzSteps(i + 1)
		}(i)
	}

	// 等待所有 goroutine 完成
	wg.Wait()

	// 輸出結果
	fmt.Println(out)
}