docs: 更新项目文档和添加项目logo

- 更新README.md，改善项目文档结构和内容 - 添加项目logo文件assets/logo.png，提升项目视觉识别度 - 完善帮助文本描述，明确说明使用默认参数和默认python解释器的行为
2025-11-24 18:28:07 +08:00
parent 5ffacbe46b
commit be88dc8f27
3 changed files with 133 additions and 103 deletions
--- a/README.md
+++ b/README.md
@@ -1,162 +1,192 @@
-# PyGILnoGILBench —— Python GIL vs. NoGIL 多线程性能基准测试工具
+<div align="center">

-一个用于对比 **Python 单线程、GIL 多线程、NoGIL 多线程** 在 CPU 密集型任务上性能差异的基准测试工具。通过质数查找这一经典 CPU 密集型任务，直观展示 GIL（全局解释器锁）对 Python 多线程性能的影响，以及 NoGIL 版本的并行加速效果。
+<div style="margin: 20px 0;">
+  <img src="./assets/logo.png" width="120" height="120" alt="PyGILnoGILBenchLogo" style="border-radius: 20px; box-shadow: 0 8px 32px rgba(0, 217, 255, 0.3);">
+</div>

-## 核心功能
+# 🚀 PyGILnoGILBench

-1. **多模式对比**：支持同时测试单线程、GIL 多线程、NoGIL 多线程三种模式。
-2. **自定义 Python 解释器**：允许用户指定不同 Python 版本的可执行文件（如标准 GIL 版本、Python 3.13+ NoGIL 版本、PyPy 等）。
-3. **详细日志模式**：通过 `-v/--verbose` 选项查看每个线程的实时运行日志。
-4. **模块化设计**：采用 `src` 目录结构，代码解耦，易于扩展和维护。
-5. **结果验证**：自动验证三种模式的测试结果一致性，确保数据可靠。
-6. **性能报告**：测试完成后生成直观的性能对比报告，包含耗时、相对速度等指标。
+## Python GIL vs. NoGIL 多线程性能基准测试工具

-## 适用场景
+[![Python Version](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org) [![NoGIL Support](https://img.shields.io/badge/NoGIL-3.13%2B%20%2F%20PyPy-green.svg)](https://peps.python.org/pep-0703/) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Dependencies](https://img.shields.io/badge/Dependencies-None-brightgreen.svg)](pyproject.toml) [![Status](https://img.shields.io/badge/Status-Active-brightgreen.svg)](https://drdfilenest.xyz:8443/root/PyGILnoGILBench)

-* 开发者评估 Python NoGIL 版本对 CPU 密集型任务的加速效果。
-* 学习和理解 GIL 对 Python 多线程的影响。
-* 对比不同 Python 解释器在多线程场景下的性能表现。
-* 优化 CPU 密集型任务的多线程实现方案。
+<div>
+</div>
+</div>

-## 环境要求
+> ⚡ **Python 多线程性能对比工具**
+> 直观展示 GIL 限制与 NoGIL 并行的性能差异
+> 支持自定义 Python 解释器、多种测试模式和灵活的输出格式

-* 操作系统：Windows、macOS、Linux（支持 Python 的所有平台）。
-* Python 版本：
+一个用于对比 **Python 单线程、GIL 多线程、NoGIL 多线程** 在 CPU 密集型任务上性能差异的专业基准测试工具。通过质数查找经典 CPU 密集型任务，直观展示 GIL（全局解释器锁）对 Python 多线程性能的影响，以及 NoGIL 版本的并行加速效果。

-  * 至少 1 个标准 GIL 版本（推荐 Python 3.9+）。
-  * 可选 NoGIL 版本（Python 3.13+ 启用 `--disable-gil` 编译，或 PyPy）。
-* 依赖：无额外第三方依赖（仅使用 Python 标准库）。
+## 🚀 核心功能

-## 安装步骤
+- **多模式对比测试**：支持同时测试单线程、GIL 多线程、NoGIL 多线程三种运行模式
+- **自定义 Python 解释器**：允许指定不同 Python 版本的可执行文件（标准 GIL 版本、Python 3.13+ NoGIL 版本、PyPy 等）
+- **详细日志模式**：通过 `-v/--verbose` 选项实时查看每个线程的运行日志
+- **静默模式**：通过 `-q/--quiet` 选项使用默认参数，仅显示最终测试报告
+- **灵活输出格式**：支持将测试报告保存为 JSON、CSV 或 TXT 格式
+- **测试控制选项**：支持跳过特定测试类型、设置测试超时时间等
+- **直观性能报告**：测试完成后生成包含耗时、相对速度等指标的对比报告

-1. **克隆 / 下载项目**：
+## 📋 适用场景

+- 开发者评估 Python NoGIL 版本对 CPU 密集型任务的加速效果
+- 学习和理解 GIL 对 Python 多线程性能的影响机制
+- 对比不同 Python 解释器在多线程场景下的性能表现
+- 优化 CPU 密集型任务的多线程实现方案
+
+## 📁 项目结构
+
+```bash
+PyGILnoGILBench/
+├── main.py                 # 基准测试主程序入口
+├── pyproject.toml          # 项目配置文件
+├── LICENSE                 # 许可证文件
+├── README.md               # 项目说明文档
+└── src/                    # 核心功能模块目录
+    ├── primes.py           # 质数判断核心函数
+    ├── single_thread.py    # 单线程实现方案
+    ├── gil_thread.py       # GIL多线程实现（动态负载均衡）
+    ├── nogil_thread.py     # NoGIL多线程实现（静态任务划分）
+    └── test_worker.py      # 测试工作线程
 ```
-git clone https://drdfilenest.xyz:8443/root/PyGILnoGILBench.git

+## 🔧 环境要求
+
+- **操作系统**：Windows、macOS、Linux（支持 Python 的所有平台）
+- **Python 版本**：
+  - 主程序运行环境：Python 3.9 或更高版本
+  - 至少 1 个标准 GIL 版本用于测试
+  - 可选 1 个 NoGIL 版本（Python 3.14+ Free Thread 版本 / 3.13.9+ Free Thread 版本 / Python 3.13+ 启用 `--disable-gil` 编译，或 PyPy）
+- **依赖**：无第三方依赖
+- **工具支持**：项目配置支持使用 `uv` 包管理器（可选）
+
+## 📥 安装步骤
+
+1. **克隆项目仓库**：
+
+```bash
+git clone https://drdfilenest.xyz:8443/root/PyGILnoGILBench.git
 cd PyGILnoGILBench
 ```

-1. **验证环境**：确保系统中已安装至少一个 Python 解释器（GIL 或 NoGIL 版本），并能通过路径访问。
+2. **验证运行环境**：确保系统中已安装至少一个 Python 解释器（GIL 或 NoGIL 版本），并能通过路径访问。

-## 使用方法
+## 🎯 使用方法

-### 基本运行
+### 基本命令

-在项目根目录执行以下命令启动测试：
+使用标准 Python 解释器运行：

-```
-python main.py
+```bash
+python main.py [OPTIONS]
 ```

-### 详细模式（显示线程日志）
+或使用 `uv` 包管理器（可选）：

+```bash
+uv sync
+uv run main.py [OPTIONS]
 ```
-python main.py -v

-或
+### 可用命令行选项

-python main.py --verbose
-```
+| 选项                                       | 描述                                                    |
+| ------------------------------------------ | ------------------------------------------------------- |
+| `-h, --help`                             | 显示详细帮助信息并退出                                  |
+| `-v, --verbose`                          | 启用详细模式，显示每个线程的实时运行日志                |
+| `-q, --quiet`                            | 启用静默模式，使用默认测试参数，仅显示最终报告          |
+| `-n NUM_PRIMES, --num-primes NUM_PRIMES` | 指定要寻找的质数总数（默认：30000）                     |
+| `-t THREADS, --threads THREADS`          | 指定多线程测试时使用的线程数（默认：CPU核心数）         |
+| `-s TEST_TYPE, --skip TEST_TYPE`         | 跳过指定类型的测试（可选值：single, gil, nogil）        |
+| `-l TIMEOUT, --timeout TIMEOUT`          | 单个测试的超时时间（秒，默认：300）                     |
+| `-o OUTPUT_FILE, --output OUTPUT_FILE`   | 将测试报告保存到指定文件（支持格式：.json, .csv, .txt） |

 ### 测试流程

 1. **输入 Python 解释器路径**：

-   脚本会提示输入 3 个 Python 解释器路径（可重复输入同一路径，也可分别输入不同版本）：
+   脚本会提示输入需要的 Python 解释器路径（根据是否跳过测试类型决定）：

-   示例（Windows）：
+   **Windows 示例**：

-```
-1\. 用于单线程测试的Python路径: C:\Python311\python3.14.exe
+   ```bash
+   1. 用于单线程测试的Python路径: C:\Python314\python.exe
+   2. 用于GIL多线程测试的Python路径: C:\Python314\python.exe
+   3. 用于NoGIL多线程测试的Python路径: C:\Python314\python3.14t.exe
+   ```

-2\. 用于GIL多线程测试的Python路径: C:\Python311\python3.14.exe
+   **Linux/macOS 示例**：

-3\. 用于NoGIL多线程测试的Python路径: C:\Python314\python3.14t.exe
-```
+   ```bash
+   1. 用于单线程测试的Python路径: /usr/bin/python3
+   2. 用于GIL多线程测试的Python路径: /usr/bin/python3
+   3. 用于NoGIL多线程测试的Python路径: /usr/local/bin/python3.14t
+   ```

-示例（Linux/macOS）：
+   > 💡 **提示**：在静默模式下，将自动使用当前运行脚本的 Python 解释器。
+   >
+2. **查看测试结果**：

-```
-1\. 用于单线程测试的Python路径: /usr/bin/python3.14
+   测试完成后，脚本会生成直观的性能对比报告：

-2\. 用于GIL多线程测试的Python路径: /usr/bin/python3.14
-
-3\. 用于NoGIL多线程测试的Python路径: /usr/local/bin/python3.14t
-```
-
-* 用于单线程测试的 Python 路径。
-* 用于 GIL 多线程测试的 Python 路径。
-* 用于 NoGIL 多线程测试的 Python 路径。
-
-1. **设置测试参数**：
-
-* 要寻找的质数总数（例如 `30000`，数值越大测试耗时越长，结果越准确）。
-* 多线程测试的线程数（建议设置为 CPU 核心数，例如 `8`）。
-
-1. **查看测试结果**：
-
-   测试完成后，脚本会生成性能对比报告，示例如下：
-
-```
+```bash
+============================================================
 测试完成! 性能对比报告如下:
 ============================================================
-测试类型          耗时(秒)      相对速度      质数数量
+
+测试类型            耗时(秒)        相对速度         质数数量
 ------------------------------------------------------------
-单线程            10.23        1.00x         30000
-GIL多线程         11.56        0.88x         30000
-NoGIL多线程       2.87         3.56x         30000
+单线程             0.29         0.40        x 30000
+GIL多线程          0.38         0.31        x 30000
+NoGIL多线程        0.12         1.00        x 30000
+
+============================================================
 ```

-## 项目结构
+## 🔬 测试原理

-```
-PyGILnoGILBench/
-├── main.py                 # 基准测试主程序
-└── src/                    # 核心功能模块目录
-    ├── __init__.py     # 包初始化文件
-    ├── primes.py           # 质数判断核心函数
-    ├── single_thread.py   # 单线程实现
-    ├── gil_thread.py      # GIL多线程实现（动态负载均衡）
-    ├── nogil_thread.py    # NoGIL多线程实现（静态任务划分）
-    └── test_worker.py     # 测试工作线程
-```
+### 核心测试任务

-## 测试原理
+采用 **质数查找** 作为 CPU 密集型任务（无 I/O 操作，纯计算密集型）：

-### 核心任务
-
-采用 **质数查找** 作为 CPU 密集型任务（无 I/O 操作，纯计算）：
-
-* 单线程：从 2 开始依次检查每个数字，直到找到指定数量的质数。
-* GIL 多线程：使用动态负载均衡（共享计数器 + 锁），多个线程竞争获取待检查数字，避免静态划分导致的负载不均。
-* NoGIL 多线程：使用静态任务划分（无锁设计），将数字范围均匀拆分给每个线程，充分利用多核并行计算。
+- **单线程实现**：从 2 开始依次检查每个数字，直到找到指定数量的质数
+- **GIL 多线程实现**：使用动态负载均衡策略，通过共享计数器和锁机制，让多个线程竞争获取待检查的数字。这种方式避免了静态划分可能导致的负载不均问题，但在有 GIL 的环境下仍会受限于单线程执行速度
+- **NoGIL 多线程实现**：使用静态任务划分策略，将搜索范围预先均匀分配给每个线程。每个线程独立工作，无需锁竞争，能充分利用多核 CPU 资源实现真正的并行计算

 ### 性能影响因素

-* **GIL 限制**：标准 Python 的 GIL 导致多线程无法真正并行，仅能并发执行，线程切换和锁竞争会增加开销。
-* **NoGIL 并行**：无 GIL 版本可充分利用多核 CPU，静态任务划分避免锁竞争，显著提升 CPU 密集型任务性能。
-* **线程数**：线程数建议与 CPU 核心数一致，过多线程会导致上下文切换开销。
+- **GIL 限制**：标准 Python 的 GIL 导致多线程无法真正并行，仅能并发执行。线程切换和锁竞争会增加额外开销，因此 GIL 多线程在 CPU 密集型任务上可能比单线程更慢
+- **NoGIL 并行**：无 GIL 版本可充分利用多核 CPU 实现真正的并行计算。静态任务划分避免了锁竞争，显著提升 CPU 密集型任务性能
+- **线程数设置**：线程数建议与 CPU 核心数一致。过多线程会导致上下文切换开销增加，可能降低整体性能
+- **任务复杂度**：质数查找任务的复杂度随数值增大而增加，测试结果的可靠性与质数总数相关

-## 常见问题
+## ❓ 常见问题

 ### 1. NoGIL 版本测试无加速效果

-* 线程数是否超过 CPU 核心数，导致上下文切换开销。
-* 测试的质数总数是否过小（建议至少 `30000` 以上，确保任务耗时足够长）。
+- **检查线程数**：线程数是否超过 CPU 核心数，导致上下文切换开销
+- **调整质数数量**：测试的质数总数是否过小（建议至少 `30000` 以上，确保任务耗时足够长）
+- **验证解释器**：是否正确使用了 NoGIL 版本的 Python

 ### 2. 测试结果不一致

-* 确保所有 Python 版本的解释器路径正确，且无语法兼容性问题（推荐 Python 3.8+）。
-* 检查系统负载是否过高，测试时避免运行其他 CPU 密集型任务。
+- **解释器一致性**：确保所有 Python 版本的解释器路径正确，且无语法兼容性问题（推荐 Python 3.9+）
+- **系统负载**：检查测试时系统负载是否过高，避免运行其他 CPU 密集型任务
+- **多次测试**：建议多次运行测试取平均值，以减少随机因素影响

-## 注意事项
+### 3. 测试报告文件保存失败

-1. 测试耗时与质数总数正相关：总数越大，结果越准确，但耗时越长（建议根据 CPU 性能调整，入门级 CPU 可先测试 `10000` 个质数）。
-2. NoGIL 版本要求：Python 3.13+ 需手动编译并启用 `--disable-gil` 选项，或使用 PyPy（自带无 GIL 支持）。
-3. 线程数设置：建议设置为 CPU 核心数（例如 8 核 CPU 设置为 8），过多线程会降低性能。
-4. 结果解读：GIL 多线程在 CPU 密集型任务上可能比单线程慢（正常现象），NoGIL 多线程应展现 2-8 倍加速（取决于核心数）。
+- **路径权限**：检查文件路径是否正确，是否有写入权限
+- **文件格式**：确保文件扩展名与支持的格式匹配（.json, .csv, .txt）
+- **Python 版本**：确保使用的 Python 解释器版本兼容（推荐 Python 3.8+）

-## 许可证
+## 📄 许可证

-本项目采用 MIT 许可证，详情见 [LICENSE](LICENSE) 文件。
+本项目基于 **MIT 许可证** 开源，您可以在遵守许可证条款的前提下自由使用、修改和分发本项目的代码。
+
+---
+
+**PyGILnoGILBench** —— 让 Python 多线程性能测试更直观！
--- a/assets/logo.png
+++ b/assets/logo.png
--- a/main.py
+++ b/main.py
@@ -37,7 +37,7 @@ def print_custom_help():
 {HEADER}Options:{RESET}
  {OPTION}-h, --help{RESET}            显示此帮助信息并退出。
  {OPTION}-v, --verbose{RESET}         启用详细模式。在测试过程中打印每个线程的实时日志。
-  {OPTION}-q, --quiet{RESET}           启用静默模式。只在测试结束后打印最终报告，抑制其他所有输出。
+  {OPTION}-q, --quiet{RESET}           启用静默模式。使用默认参数和默认python解释器，只在测试结束后打印最终报告，抑制其他所有输出。

  {OPTION}-n NUM_PRIMES, --num-primes NUM_PRIMES{RESET}
                        指定要寻找的质数总数。