1from monitor import Monitor
2
3Monitor.init(endpoint="http://localhost:9090/v1/events", app="my-hook")
4
5# 做事...
6Monitor.event("hook.run", {"hook": "branch-check"})
7
8# 結束前必須呼叫 close
9Monitor.close()  # close 內同步 flush，不依賴 daemon thread

1當時的考量：
21. 單核 CPU 是主流
32. 簡化記憶體管理（參考計數）
43. 簡化 C 擴展開發
54. 避免細粒度鎖的複雜性

 1// 沒有 GIL 時，這個操作不是原子的
 2Py_INCREF(obj);
 3// 展開後：
 4// 1. 讀取 ob_refcnt
 5// 2. 加 1
 6// 3. 寫回 ob_refcnt
 7
 8// 如果兩個執行緒同時執行，可能會：
 9// Thread 1: 讀取 refcnt = 1
10// Thread 2: 讀取 refcnt = 1
11// Thread 1: 寫入 refcnt = 2
12// Thread 2: 寫入 refcnt = 2  ← 錯誤！應該是 3

1// 簡化版的 GIL 結構
2typedef struct {
3    PyMutex mutex;           // 互斥鎖
4    PyThread_type_lock lock; // 執行緒鎖
5    int locked;              // 鎖定狀態
6} _gil_runtime_state;

 1# 1. I/O 操作
 2f = open('file.txt', 'r')  # 釋放 GIL
 3content = f.read()          # 釋放 GIL
 4
 5# 2. sleep
 6import time
 7time.sleep(1)  # 釋放 GIL
 8
 9# 3. 某些 C 擴展操作
10import numpy as np
11result = np.dot(a, b)  # NumPy 可能釋放 GIL
12
13# 4. 定期釋放（每 N 個 bytecode 指令）
14# Python 3.2+ 預設約每 5ms 檢查一次

1import sys
2
3# 查看切換間隔（秒）
4print(sys.getswitchinterval())  # 0.005（5ms）
5
6# 設定切換間隔
7sys.setswitchinterval(0.001)  # 1ms

 1// C 擴展可以明確釋放 GIL
 2static PyObject* compute_intensive(PyObject* self, PyObject* args) {
 3    // 釋放 GIL
 4    Py_BEGIN_ALLOW_THREADS
 5
 6    // 這裡的程式碼可以並行執行
 7    do_heavy_computation();
 8
 9    // 重新獲取 GIL
10    Py_END_ALLOW_THREADS
11
12    Py_RETURN_NONE;
13}

 1import threading
 2import time
 3
 4def cpu_intensive(n):
 5    """純 Python CPU 密集計算"""
 6    total = 0
 7    for i in range(n):
 8        total += i * i
 9    return total
10
11def benchmark(func, args, num_threads):
12    threads = []
13    start = time.perf_counter()
14
15    for _ in range(num_threads):
16        t = threading.Thread(target=func, args=args)
17        threads.append(t)
18        t.start()
19
20    for t in threads:
21        t.join()
22
23    return time.perf_counter() - start
24
25n = 5_000_000
26
27# 單執行緒
28time_1 = benchmark(cpu_intensive, (n,), 1)
29print(f"1 執行緒: {time_1:.3f}s")
30
31# 多執行緒（受 GIL 限制）
32time_4 = benchmark(cpu_intensive, (n,), 4)
33print(f"4 執行緒: {time_4:.3f}s")
34
35# 結果：多執行緒可能更慢（執行緒切換開銷）

 1import threading
 2import time
 3import urllib.request
 4
 5def io_intensive(url):
 6    """I/O 密集操作"""
 7    try:
 8        with urllib.request.urlopen(url, timeout=5) as f:
 9            return len(f.read())
10    except:
11        return 0
12
13urls = ["https://example.com"] * 10
14
15# 單執行緒
16start = time.perf_counter()
17for url in urls:
18    io_intensive(url)
19time_sequential = time.perf_counter() - start
20print(f"序列: {time_sequential:.3f}s")
21
22# 多執行緒
23start = time.perf_counter()
24threads = [threading.Thread(target=io_intensive, args=(url,)) for url in urls]
25for t in threads:
26    t.start()
27for t in threads:
28    t.join()
29time_parallel = time.perf_counter() - start
30print(f"並行: {time_parallel:.3f}s")
31
32# 結果：多執行緒明顯更快（I/O 時釋放 GIL）

 1傳統參考計數：
 2┌─────────────────────────────────────┐
 3│  ob_refcnt = 2                      │
 4│  每次操作都需要原子操作或鎖         │
 5└─────────────────────────────────────┘
 6
 7偏向參考計數：
 8┌─────────────────────────────────────┐
 9│  local_refcnt[thread_id] = 1        │  ← 每個執行緒有自己的計數
10│  local_refcnt[thread_id] = 1        │
11│  shared_refcnt = 0                  │  ← 共享計數
12└─────────────────────────────────────┘
13
14優點：
15- 大多數操作只需更新區域計數（無鎖）
16- 只有跨執行緒參考才需要更新共享計數

 1# Free-threading 中的優化策略
 2
 3# 對於不朽物件（immortal objects）
 4# 如 None、True、False、小整數
 5# 完全跳過參考計數
 6
 7# 對於局部物件
 8# 使用區域計數，無需同步
 9
10# 只有跨執行緒共享的物件
11# 才需要使用原子操作

 1傳統 CPython（有 GIL）：
 2┌──────────────────────────────────────────┐
 3│  Thread 1  │  Thread 2  │  Thread 3      │
 4│     ↓            ↓            ↓          │
 5│     └────────────┼────────────┘          │
 6│                  ↓                       │
 7│               [ GIL ]                    │
 8│                  ↓                       │
 9│        [ Python Interpreter ]            │
10│                  ↓                       │
11│          [ 共享記憶體 ]                  │
12└──────────────────────────────────────────┘
13
14Free-threaded CPython：
15┌──────────────────────────────────────────┐
16│  Thread 1  │  Thread 2  │  Thread 3      │
17│     ↓            ↓            ↓          │
18│  [Local]     [Local]     [Local]         │
19│  State       State       State           │
20│     ↓            ↓            ↓          │
21│     └────────────┼────────────┘          │
22│                  ↓                       │
23│     [ 原子操作 / 鎖 / 無鎖資料結構 ]     │
24│                  ↓                       │
25│          [ 共享記憶體 ]                  │
26└──────────────────────────────────────────┘

 1import sys
 2
 3def check_environment():
 4    """檢查 Free-threading 環境"""
 5    try:
 6        gil_enabled = sys._is_gil_enabled()
 7        print(f"GIL 啟用: {gil_enabled}")
 8        return not gil_enabled
 9    except AttributeError:
10        print("傳統 Python（有 GIL）")
11        return False
12
13is_free_threaded = check_environment()

 1import threading
 2
 3# 不安全：共享可變狀態
 4counter = 0
 5
 6def unsafe_increment():
 7    global counter
 8    for _ in range(100000):
 9        counter += 1  # 競爭條件！
10
11# 安全：使用鎖
12counter = 0
13lock = threading.Lock()
14
15def safe_increment():
16    global counter
17    for _ in range(100000):
18        with lock:
19            counter += 1
20
21# 更好：使用原子操作或不可變資料
22from collections import Counter
23from concurrent.futures import ThreadPoolExecutor
24
25def better_approach(data_chunk):
26    """每個執行緒處理自己的資料，最後合併"""
27    local_count = 0
28    for item in data_chunk:
29        local_count += process(item)
30    return local_count
31
32with ThreadPoolExecutor() as executor:
33    results = executor.map(better_approach, data_chunks)
34    total = sum(results)

 1import sys
 2
 3def compute(data):
 4    """根據環境選擇策略"""
 5    free_threaded = getattr(sys, '_is_gil_enabled', lambda: True)() == False
 6
 7    if free_threaded:
 8        # 可以安全使用多執行緒
 9        return parallel_compute_threading(data)
10    else:
11        # 使用多進程或保持單執行緒
12        return parallel_compute_multiprocess(data)

 1你的任務是什麼類型？
 2│
 3├── I/O 密集（網路、檔案、資料庫）
 4│   └── 使用 threading 或 asyncio
 5│       （GIL 不影響）
 6│
 7└── CPU 密集（計算、處理）
 8    │
 9    ├── 使用 Free-threaded Python (3.13+)?
10    │   ├── 是 → 可以使用 threading
11    │   └── 否 → 選擇以下方案
12    │
13    ├── 可以用 C 擴展？
14    │   └── NumPy、Cython 等（會釋放 GIL）
15    │
16    └── 純 Python？
17        └── 使用 multiprocessing 或 ProcessPoolExecutor

1Python 3.13 (2024): 實驗性 Free-threading
2Python 3.14 (2025): 正式支援 Free-threading
3Python 3.15/3.16:   可能成為預設
4未來:               GIL 可能完全移除

1# 檢查套件是否支援 Free-threading
2# pip index versions package-name
3
4# 主要框架的支援狀態（2025年底）
5# NumPy 2.1+:       支援
6# pandas 2.2+:      支援
7# scikit-learn 1.6+: 支援
8# PyTorch 2.6+:     支援

1傳統 Python（有 GIL）：
2┌─────────────────────────────────┐
3│  Thread 1  →  執行中             │
4│  Thread 2  →  等待 GIL...        │
5│  Thread 3  →  等待 GIL...        │
6│  Thread 4  →  等待 GIL...        │
7└─────────────────────────────────┘
8   同一時間只有一個執行緒能執行 Python 程式碼

1Free-threaded Python（無 GIL）：
2┌─────────────────────────────────┐
3│  Thread 1  →  執行中  (Core 1)   │
4│  Thread 2  →  執行中  (Core 2)   │
5│  Thread 3  →  執行中  (Core 3)   │
6│  Thread 4  →  執行中  (Core 4)   │
7└─────────────────────────────────┘
8   多個執行緒可以真正並行執行

1# 使用 deadsnakes PPA
2sudo add-apt-repository ppa:deadsnakes/ppa
3sudo apt update
4sudo apt install python3.13-nogil
5# 或
6sudo apt install python3.14-nogil

1./configure --disable-gil
2make -j$(nproc)
3sudo make install

1# 檢查版本資訊
2python3.14t -VV
3# 輸出應包含 "free-threading build"
4
5# 確認 GIL 狀態
6python3.14t -c "import sys; print('GIL enabled:', sys._is_gil_enabled())"
7# 應該輸出：GIL enabled: False

1# 強制停用 GIL（即使有不相容模組）
2PYTHON_GIL=0 python3.14t script.py
3
4# 或使用命令列參數
5python3.14t -Xgil=0 script.py
6
7# 強制啟用 GIL（在 free-threaded 版本中）
8python3.14t -Xgil=1 script.py

 1import sys
 2
 3def is_free_threaded() -> bool:
 4    """檢查是否在 free-threaded 模式執行"""
 5    try:
 6        return not sys._is_gil_enabled()
 7    except AttributeError:
 8        # Python 3.12 或更早版本沒有這個函式
 9        return False
10
11def get_python_build_info() -> dict:
12    """取得 Python 建置資訊"""
13    return {
14        "version": sys.version,
15        "free_threaded": is_free_threaded(),
16        "gil_enabled": getattr(sys, '_is_gil_enabled', lambda: True)(),
17    }
18
19if __name__ == "__main__":
20    info = get_python_build_info()
21    print(f"Python 版本: {info['version']}")
22    print(f"Free-threaded: {info['free_threaded']}")
23    print(f"GIL 啟用: {info['gil_enabled']}")

 1import threading
 2import time
 3import sys
 4
 5def cpu_intensive(n: int) -> int:
 6    """CPU 密集計算：計算平方和"""
 7    return sum(i * i for i in range(n))
 8
 9def sequential_compute(numbers: list[int]) -> list[int]:
10    """序列計算"""
11    return [cpu_intensive(n) for n in numbers]
12
13def parallel_compute(numbers: list[int]) -> list[int]:
14    """並行計算"""
15    results = [None] * len(numbers)
16
17    def worker(idx: int, n: int):
18        results[idx] = cpu_intensive(n)
19
20    threads = [
21        threading.Thread(target=worker, args=(i, n))
22        for i, n in enumerate(numbers)
23    ]
24
25    for t in threads:
26        t.start()
27    for t in threads:
28        t.join()
29
30    return results
31
32def benchmark():
33    """效能比較"""
34    numbers = [5_000_000] * 4
35
36    # 序列執行
37    start = time.perf_counter()
38    sequential_compute(numbers)
39    sequential_time = time.perf_counter() - start
40
41    # 並行執行
42    start = time.perf_counter()
43    parallel_compute(numbers)
44    parallel_time = time.perf_counter() - start
45
46    print(f"序列執行: {sequential_time:.3f}s")
47    print(f"並行執行: {parallel_time:.3f}s")
48    print(f"加速比: {sequential_time / parallel_time:.2f}x")
49
50    # 在傳統 Python 中，加速比接近 1（無改善）
51    # 在 Free-threaded Python 中，加速比接近 CPU 核心數
52
53if __name__ == "__main__":
54    try:
55        print(f"GIL 啟用: {sys._is_gil_enabled()}")
56    except AttributeError:
57        print("GIL 狀態: 無法檢測（舊版 Python）")
58
59    benchmark()

 1from concurrent.futures import ThreadPoolExecutor, as_completed
 2import time
 3import sys
 4
 5def process_chunk(chunk_id: int, size: int) -> dict:
 6    """處理一個資料區塊"""
 7    result = sum(i * i for i in range(size))
 8    return {"chunk_id": chunk_id, "result": result}
 9
10def parallel_process(num_chunks: int = 8, chunk_size: int = 2_000_000):
11    """並行處理多個資料區塊"""
12    start = time.perf_counter()
13
14    with ThreadPoolExecutor(max_workers=num_chunks) as executor:
15        futures = {
16            executor.submit(process_chunk, i, chunk_size): i
17            for i in range(num_chunks)
18        }
19
20        results = []
21        for future in as_completed(futures):
22            chunk_id = futures[future]
23            result = future.result()
24            results.append(result)
25            print(f"Chunk {chunk_id} 完成")
26
27    elapsed = time.perf_counter() - start
28    print(f"\n總耗時: {elapsed:.3f}s")
29    print(f"平均每個 chunk: {elapsed / num_chunks:.3f}s")
30
31    return results
32
33if __name__ == "__main__":
34    try:
35        print(f"Free-threaded 模式: {not sys._is_gil_enabled()}\n")
36    except AttributeError:
37        print("傳統 Python 模式\n")
38
39    parallel_process()

1┌─────────────────────────────────────────┐
2│              單一進程                     │
3│  ┌──────────┐  ┌──────────┐             │
4│  │ 解釋器 1  │  │ 解釋器 2  │             │
5│  │ (獨立)   │  │ (獨立)   │             │
6│  │ sys.path │  │ sys.path │  ← 完全隔離  │
7│  │ modules  │  │ modules  │             │
8│  └──────────┘  └──────────┘             │
9└─────────────────────────────────────────┘

 1from concurrent.futures import InterpreterPoolExecutor
 2
 3def cpu_task(n: int) -> int:
 4    """在獨立解釋器中執行的任務"""
 5    return sum(i * i for i in range(n))
 6
 7if __name__ == "__main__":
 8    numbers = [1_000_000, 2_000_000, 3_000_000, 4_000_000]
 9
10    # 使用多解釋器池
11    with InterpreterPoolExecutor(max_workers=4) as executor:
12        results = list(executor.map(cpu_task, numbers))
13
14    print(f"結果: {results}")

1# 在 3.14t 中可能有問題
2from pathlib import Path
3import threading
4
5path = Path("/some/path")
6
7def check_path():
8    # is_dir() 在多執行緒下可能有競爭條件
9    return path.is_dir()

 1# 錯誤：全域狀態未加鎖保護
 2cache = {}
 3
 4def get_cached(key):
 5    if key not in cache:
 6        cache[key] = expensive_compute(key)  # 競爭條件！
 7    return cache[key]
 8
 9# 正確：使用 Lock 保護
10import threading
11
12cache = {}
13cache_lock = threading.Lock()
14
15def get_cached_safe(key):
16    with cache_lock:
17        if key not in cache:
18            cache[key] = expensive_compute(key)
19        return cache[key]

 1# 錯誤：依賴內建型別的「隱式」執行緒安全
 2results = []
 3
 4def worker(n):
 5    result = compute(n)
 6    results.append(result)  # 在 free-threaded 中可能不安全
 7
 8# 正確：返回結果，由主執行緒收集
 9def worker_safe(n):
10    return compute(n)
11
12with ThreadPoolExecutor() as executor:
13    results = list(executor.map(worker_safe, items))

 1import sys
 2
 3def main():
 4    # 檢查執行環境
 5    free_threaded = getattr(sys, '_is_gil_enabled', lambda: True)() == False
 6
 7    if free_threaded:
 8        print("使用 Free-threaded 最佳化路徑")
 9        run_parallel_optimized()
10    else:
11        print("使用傳統多進程路徑")
12        run_multiprocess_fallback()

1import threading
2
3# 永遠明確使用 Lock，不要依賴「可能」的執行緒安全
4lock = threading.Lock()
5
6def thread_safe_operation():
7    with lock:
8        # 關鍵區段
9        pass

 1# 使用較短的執行緒切換間隔來暴露潛在的競爭條件
 2import sys
 3sys.setswitchinterval(0.0001)  # 測試時使用
 4
 5# 運行大量並行測試
 6import concurrent.futures
 7import random
 8
 9def stress_test(func, iterations=1000):
10    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
11        futures = [executor.submit(func) for _ in range(iterations)]
12        for f in concurrent.futures.as_completed(futures):
13            f.result()  # 會拋出任何異常

 1def check_dependencies():
 2    """檢查關鍵依賴是否支援 free-threading"""
 3    import importlib.metadata
 4
 5    packages_to_check = ['numpy', 'pandas', 'scikit-learn']
 6    results = {}
 7
 8    for pkg in packages_to_check:
 9        try:
10            version = importlib.metadata.version(pkg)
11            results[pkg] = version
12        except importlib.metadata.PackageNotFoundError:
13            results[pkg] = "未安裝"
14
15    return results