celestialflow 3.2.7__tar.gz → 3.2.9__tar.gz

{celestialflow-3.2.7/src/celestialflow.egg-info → celestialflow-3.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.2.7
+Version: 3.2.9
 Summary: A flexible GRAPH-based task orchestration framework.
 Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
 License: MIT
@@ -258,98 +258,122 @@ flowchart TD
 ## 文件结构（File Structure）
 
 ```
-📁 CelestialFlow	(471MB 982KB 22B)
-    📁 .agents        	(55KB 152B)
-        📁 skills[已折叠]	(55KB 152B)
-    📁 .claude        	(99B)
-        🗄️ settings.local.json	(99B)
-    📁 .github        	(601B)
-        📁 workflows[已折叠]	(601B)
-    📁 bench          	(150KB 552B)
-        📁 [1项排除的目录]                  	(47KB 905B)
+📁 CelestialFlow	(588MB 419KB 930B)
+    📁 bench           	(296KB 806B)
+        📁 [1项排除的目录]                  	(194KB 222B)
         🐍 bench_datastructures.py          	(6KB 690B)
-        🐍 bench_execution_mode.py          	(2KB 889B)
-        🐍 bench_futures_memory.py          	(2KB 267B)
-        🐍 bench_gil_vs_nogil.py            	(10KB 159B)
-        🐍 bench_graph_mode.py              	(7KB 173B)
-        🐍 bench_hash.py                    	(7KB 39B)
+        🐍 bench_execution_mode.py          	(2KB 707B)
+        🐍 bench_futures_memory.py          	(2KB 269B)
+        🐍 bench_gil_vs_nogil.py            	(10KB 121B)
+        🐍 bench_graph_mode.py              	(7KB 450B)
+        🐍 bench_hash.py                    	(7KB 67B)
         🐍 bench_hash_container.py          	(3KB 1009B)
-        🐍 bench_hash_memory.py             	(3KB 613B)
-        🐍 bench_http_grpc.py               	(2KB 883B)
-        🐍 bench_ipc_queue.py               	(7KB 74B)
+        🐍 bench_hash_memory.py             	(3KB 642B)
+        🐍 bench_http_grpc.py               	(2KB 521B)
+        🐍 bench_ipc_queue.py               	(7KB 104B)
         🐍 bench_lock_overhead.py           	(9KB 421B)
-        🐍 bench_mpqueue_vs_shared_memory.py	(13KB 106B)
-        🐍 bench_observer.py                	(7KB 899B)
-        🐍 bench_persistence_spout.py       	(4KB 193B)
+        🐍 bench_mpqueue_vs_shared_memory.py	(13KB 127B)
+        🐍 bench_observer.py                	(7KB 860B)
+        🐍 bench_persistence_spout.py       	(4KB 340B)
         🐍 bench_queue.py                   	(5KB 857B)
         🐍 bench_requests.py                	(6KB 813B)
         🐍 bench_tqdm.py                    	(1KB 235B)
         🐍 bench_utils.py                   	(543B)
-    📁 demo           	(105KB 440B)
-        📁 [1项排除的目录]  	(61KB 883B)
-        🐍 demo_executor.py 	(1KB 504B)
+    📁 demo            	(145KB 1012B)
+        📁 [1项排除的目录]  	(100KB 9B)
+        🐍 demo_executor.py 	(1KB 495B)
         🐍 demo_funnel.py   	(2KB 289B)
-        🐍 demo_graph.py    	(3KB 615B)
-        🐍 demo_observer.py 	(4KB 293B)
-        🐍 demo_redis.py    	(9KB 201B)
-        🐍 demo_stages.py   	(4KB 519B)
-        🐍 demo_structure.py	(12KB 8B)
-        🐍 demo_utils.py    	(6KB 200B)
-    📁 dist           	(145KB 290B)
+        🐍 demo_graph.py    	(3KB 227B)
+        🐍 demo_network.py  	(3KB 729B)
+        🐍 demo_observer.py 	(4KB 270B)
+        🐍 demo_redis.py    	(9KB 81B)
+        🐍 demo_stages.py   	(4KB 219B)
+        🐍 demo_structure.py	(11KB 593B)
+        🐍 demo_utils.py    	(6KB 148B)
+    📁 dist            	(302KB 861B)
         ❓ .gitignore                          	(1B)
-        ❓ celestialflow-3.2.6-py3-none-any.whl	(78KB 975B)
-        📦 celestialflow-3.2.6.tar.gz          	(66KB 338B)
-    📁 docs           	(1MB 712KB 884B)
-        📁 en[已折叠]   	(569KB 485B)
-        📁 ja[已折叠]   	(642KB 959B)
-        📁 zh-CN[已折叠]	(524KB 464B)
-    📁 experiments    	(2KB 1015B)
-        🐍 experiment_networkx.py	(1KB 878B)
+        ❓ celestialflow-3.2.7-py3-none-any.whl	(79KB 235B)
+        📦 celestialflow-3.2.7.tar.gz          	(67KB 836B)
+        ❓ celestialflow-3.2.8-py3-none-any.whl	(83KB 244B)
+        📦 celestialflow-3.2.8.tar.gz          	(72KB 569B)
+    📁 docs            	(1MB 756KB 830B)
+        📁 en[已折叠]   	(568KB 991B)
+        📁 ja[已折叠]   	(642KB 383B)
+        📁 zh-CN[已折叠]	(569KB 480B)
+    📁 experiments     	(2KB 1021B)
+        🐍 experiment_networkx.py	(1KB 884B)
         🐍 experiment_tqdm.py    	(1KB 137B)
-    📁 img            	(5MB 871KB 242B)
+    📁 img             	(5MB 871KB 242B)
         📷 file_structure.svg  	(4MB 918KB 1000B)
         📷 logo(old).png       	(836KB 542B)
         📷 logo.png            	(122KB 747B)
         📷 scc_condensation.svg	(17KB 1B)
-    📁 src            	(1MB 767KB 296B)
-        📁 celestialflow[已折叠]         	(1MB 752KB 195B)
-        📁 celestialflow.egg-info[已折叠]	(15KB 101B)
-    📁 tests          	(3MB 902KB 217B)
-        📁 funnel[已折叠]       	(96KB 481B)
-        📁 graph[已折叠]        	(631KB 532B)
-        📁 observability[已折叠]	(157KB 435B)
-        📁 persistence[已折叠]  	(359KB 68B)
-        📁 runtime[已折叠]      	(1MB 286KB 487B)
-        📁 stage[已折叠]        	(281KB 752B)
-        📁 utils[已折叠]        	(648KB 931B)
+    📁 src             	(1MB 873KB 44B)
+        📁 celestialflow[已折叠]         	(1MB 852KB 902B)
+        📁 celestialflow.egg-info[已折叠]	(20KB 166B)
+    📁 tests           	(4MB 170KB 251B)
+        📁 benchmark[已折叠]    	(39KB 852B)
+        📁 funnel[已折叠]       	(96KB 363B)
+        📁 graph[已折叠]        	(724KB 404B)
+        📁 observability[已折叠]	(189KB 230B)
+        📁 persistence[已折叠]  	(387KB 877B)
+        📁 runtime[已折叠]      	(1MB 295KB 264B)
+        📁 stage[已折叠]        	(381KB 203B)
+        📁 utils[已折叠]        	(639KB 527B)
         📁 [1项排除的目录]      	(487KB 589B)
         🐍 conftest.py          	(1KB 38B)
         🐍 __init__.py          	(0B)
-    📁 [9项排除的目录]	(458MB 223KB 525B)
-    ❓ .env           	(468B)
-    ❓ .gitignore     	(1KB 313B)
-    📝 AGENTS.md      	(971B)
-    ❓ LICENSE        	(1KB 65B)
-    ⚙️ pyproject.toml 	(2KB 555B)
-    📝 README.md      	(12KB 272B)
-    🔒 uv.lock        	(98KB 257B)
+    📁 [12项排除的目录]	(573MB 949KB 913B)
+    ❓ .env            	(468B)
+    ❓ .gitignore      	(1KB 315B)
+    📝 AGENTS.md       	(1KB 434B)
+    ❓ LICENSE         	(1KB 65B)
+    ❓ Makefile        	(155B)
+    ⚙️ pyproject.toml  	(2KB 668B)
+    📝 README.md       	(17KB 465B)
+    🔒 uv.lock         	(121KB 572B)
 ```
 <p align="center">
-  <em>celestial-flow 3.2.7</em>
+  <em>celestial-flow 3.2.9</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.7
+- 3.2.9
   - feat:
-    - `TaskInQueue` 中添加 `maxsize` 参数, 用于限制队列最大长度
-    - 在 `graph.connect` 中添加对两个stage输入输出参数类型的检验, 如果不通过, 会有pyright报错
-  - refactor:
-    - 移除对 `tqdm` 的依赖
-      - 根据 `bench\bench_observer.py`, tqdm对轻量级任务影响有限
-      - 这次移除主要是为了完成尽量零第三方库依赖的目标
-    - 将 `observer` 的管理从 `executor` 转到 `metric`
+    - [IMPORTANT] 移除 `stage` 中 `stage_mode`，并添加 `graph_mode`
+      - 破坏性更新
+      - `stage_mode` 可以细粒度的控制每个 `TaskStage` 在图中的模式，但经过多年使用，我认为这种细粒度的控制并无必要，反而无谓的增加理解成本
+      - `graph_mode` 则提供了更粗粒度的控制，用于统一控制所有 `TaskStage` 在图中是串行/多线程/并发运行，适用于大多数场景
+      - 同时完善了 `graph_mode`(serial/thread/async) * `execution_mode`(serial/thread/async) 总共 9 种组合模式
+    - 移除 `schedule_mode`
+      - 破坏性更新
+      - 这个模式带来了许多复杂度，但没有与原先的 `stage_mode / execution_mode` 产生明显的组合优势
+    - 在 `get_graph_analysis` 中添加 `graph_mode`
+      - 这个函数主要用于给web端提供信息
+      - web端代码已经同步修改
+    - 添加新的 `warning` 项，当图不是 dag 且 `graph_mode=serial` 时触发
+    - 移除 `task_executor` 中的参数 `persist_result`
+      - 这是为了简化代码逻辑，同时也使所有任务的最终状态（包括：成功/失败/未执行）都能被统一存储
+    - 将 `task.retry` 事件降级，不再申请单独事件ID，不再在 `lifecycle` 中留痕
+  - reafactor:
+    - 合并 `benchmark` 相关函数对 sync 与 async 两种模式的执行
+      - 性能无差异，代码好看一些
+    - 将原本的 `fallback` 改名为 `lifecycle`
+      - 早在重构原本的 `fail` 时就想起个更恰当的名字，这个版本才实现
+    - 将 `graph.source_lists` 改为 `graph.source_names`
+      - `graph.source_lists` 直接存储节点的引用，而 `graph.source_names` 存储节点的名称
+    - 所有的 `log` / `lifecycle` 文件统一改名为 `flow_log` / `flow_lifecycle`
+    - 删除 `graph` 中的 `out_edges` `in_edges`
+      - 现在由 `OrderGraph` 负责管理边关系
+    - 在 `tarjan_scc` 中使用 DFS 取代原先的递归逻辑
+    - 将 `util_graph` 改名为 `util_order_graph`
+  - fix:
+    - 修复最后一次 report 无法正常上传的问题
+    - 修复 `graph.run` / `graph.run_async` 中 `is_put_signal` 参数没有生效的问题
+  - chore：
+    - 更新文档
 
 更多过往日志可看:
 

{celestialflow-3.2.7 → celestialflow-3.2.9}/README.md

@@ -239,98 +239,122 @@ flowchart TD
 ## 文件结构（File Structure）
 
 ```
-📁 CelestialFlow	(471MB 982KB 22B)
-    📁 .agents        	(55KB 152B)
-        📁 skills[已折叠]	(55KB 152B)
-    📁 .claude        	(99B)
-        🗄️ settings.local.json	(99B)
-    📁 .github        	(601B)
-        📁 workflows[已折叠]	(601B)
-    📁 bench          	(150KB 552B)
-        📁 [1项排除的目录]                  	(47KB 905B)
+📁 CelestialFlow	(588MB 419KB 930B)
+    📁 bench           	(296KB 806B)
+        📁 [1项排除的目录]                  	(194KB 222B)
         🐍 bench_datastructures.py          	(6KB 690B)
-        🐍 bench_execution_mode.py          	(2KB 889B)
-        🐍 bench_futures_memory.py          	(2KB 267B)
-        🐍 bench_gil_vs_nogil.py            	(10KB 159B)
-        🐍 bench_graph_mode.py              	(7KB 173B)
-        🐍 bench_hash.py                    	(7KB 39B)
+        🐍 bench_execution_mode.py          	(2KB 707B)
+        🐍 bench_futures_memory.py          	(2KB 269B)
+        🐍 bench_gil_vs_nogil.py            	(10KB 121B)
+        🐍 bench_graph_mode.py              	(7KB 450B)
+        🐍 bench_hash.py                    	(7KB 67B)
         🐍 bench_hash_container.py          	(3KB 1009B)
-        🐍 bench_hash_memory.py             	(3KB 613B)
-        🐍 bench_http_grpc.py               	(2KB 883B)
-        🐍 bench_ipc_queue.py               	(7KB 74B)
+        🐍 bench_hash_memory.py             	(3KB 642B)
+        🐍 bench_http_grpc.py               	(2KB 521B)
+        🐍 bench_ipc_queue.py               	(7KB 104B)
         🐍 bench_lock_overhead.py           	(9KB 421B)
-        🐍 bench_mpqueue_vs_shared_memory.py	(13KB 106B)
-        🐍 bench_observer.py                	(7KB 899B)
-        🐍 bench_persistence_spout.py       	(4KB 193B)
+        🐍 bench_mpqueue_vs_shared_memory.py	(13KB 127B)
+        🐍 bench_observer.py                	(7KB 860B)
+        🐍 bench_persistence_spout.py       	(4KB 340B)
         🐍 bench_queue.py                   	(5KB 857B)
         🐍 bench_requests.py                	(6KB 813B)
         🐍 bench_tqdm.py                    	(1KB 235B)
         🐍 bench_utils.py                   	(543B)
-    📁 demo           	(105KB 440B)
-        📁 [1项排除的目录]  	(61KB 883B)
-        🐍 demo_executor.py 	(1KB 504B)
+    📁 demo            	(145KB 1012B)
+        📁 [1项排除的目录]  	(100KB 9B)
+        🐍 demo_executor.py 	(1KB 495B)
         🐍 demo_funnel.py   	(2KB 289B)
-        🐍 demo_graph.py    	(3KB 615B)
-        🐍 demo_observer.py 	(4KB 293B)
-        🐍 demo_redis.py    	(9KB 201B)
-        🐍 demo_stages.py   	(4KB 519B)
-        🐍 demo_structure.py	(12KB 8B)
-        🐍 demo_utils.py    	(6KB 200B)
-    📁 dist           	(145KB 290B)
+        🐍 demo_graph.py    	(3KB 227B)
+        🐍 demo_network.py  	(3KB 729B)
+        🐍 demo_observer.py 	(4KB 270B)
+        🐍 demo_redis.py    	(9KB 81B)
+        🐍 demo_stages.py   	(4KB 219B)
+        🐍 demo_structure.py	(11KB 593B)
+        🐍 demo_utils.py    	(6KB 148B)
+    📁 dist            	(302KB 861B)
         ❓ .gitignore                          	(1B)
-        ❓ celestialflow-3.2.6-py3-none-any.whl	(78KB 975B)
-        📦 celestialflow-3.2.6.tar.gz          	(66KB 338B)
-    📁 docs           	(1MB 712KB 884B)
-        📁 en[已折叠]   	(569KB 485B)
-        📁 ja[已折叠]   	(642KB 959B)
-        📁 zh-CN[已折叠]	(524KB 464B)
-    📁 experiments    	(2KB 1015B)
-        🐍 experiment_networkx.py	(1KB 878B)
+        ❓ celestialflow-3.2.7-py3-none-any.whl	(79KB 235B)
+        📦 celestialflow-3.2.7.tar.gz          	(67KB 836B)
+        ❓ celestialflow-3.2.8-py3-none-any.whl	(83KB 244B)
+        📦 celestialflow-3.2.8.tar.gz          	(72KB 569B)
+    📁 docs            	(1MB 756KB 830B)
+        📁 en[已折叠]   	(568KB 991B)
+        📁 ja[已折叠]   	(642KB 383B)
+        📁 zh-CN[已折叠]	(569KB 480B)
+    📁 experiments     	(2KB 1021B)
+        🐍 experiment_networkx.py	(1KB 884B)
         🐍 experiment_tqdm.py    	(1KB 137B)
-    📁 img            	(5MB 871KB 242B)
+    📁 img             	(5MB 871KB 242B)
         📷 file_structure.svg  	(4MB 918KB 1000B)
         📷 logo(old).png       	(836KB 542B)
         📷 logo.png            	(122KB 747B)
         📷 scc_condensation.svg	(17KB 1B)
-    📁 src            	(1MB 767KB 296B)
-        📁 celestialflow[已折叠]         	(1MB 752KB 195B)
-        📁 celestialflow.egg-info[已折叠]	(15KB 101B)
-    📁 tests          	(3MB 902KB 217B)
-        📁 funnel[已折叠]       	(96KB 481B)
-        📁 graph[已折叠]        	(631KB 532B)
-        📁 observability[已折叠]	(157KB 435B)
-        📁 persistence[已折叠]  	(359KB 68B)
-        📁 runtime[已折叠]      	(1MB 286KB 487B)
-        📁 stage[已折叠]        	(281KB 752B)
-        📁 utils[已折叠]        	(648KB 931B)
+    📁 src             	(1MB 873KB 44B)
+        📁 celestialflow[已折叠]         	(1MB 852KB 902B)
+        📁 celestialflow.egg-info[已折叠]	(20KB 166B)
+    📁 tests           	(4MB 170KB 251B)
+        📁 benchmark[已折叠]    	(39KB 852B)
+        📁 funnel[已折叠]       	(96KB 363B)
+        📁 graph[已折叠]        	(724KB 404B)
+        📁 observability[已折叠]	(189KB 230B)
+        📁 persistence[已折叠]  	(387KB 877B)
+        📁 runtime[已折叠]      	(1MB 295KB 264B)
+        📁 stage[已折叠]        	(381KB 203B)
+        📁 utils[已折叠]        	(639KB 527B)
         📁 [1项排除的目录]      	(487KB 589B)
         🐍 conftest.py          	(1KB 38B)
         🐍 __init__.py          	(0B)
-    📁 [9项排除的目录]	(458MB 223KB 525B)
-    ❓ .env           	(468B)
-    ❓ .gitignore     	(1KB 313B)
-    📝 AGENTS.md      	(971B)
-    ❓ LICENSE        	(1KB 65B)
-    ⚙️ pyproject.toml 	(2KB 555B)
-    📝 README.md      	(12KB 272B)
-    🔒 uv.lock        	(98KB 257B)
+    📁 [12项排除的目录]	(573MB 949KB 913B)
+    ❓ .env            	(468B)
+    ❓ .gitignore      	(1KB 315B)
+    📝 AGENTS.md       	(1KB 434B)
+    ❓ LICENSE         	(1KB 65B)
+    ❓ Makefile        	(155B)
+    ⚙️ pyproject.toml  	(2KB 668B)
+    📝 README.md       	(17KB 465B)
+    🔒 uv.lock         	(121KB 572B)
 ```
 <p align="center">
-  <em>celestial-flow 3.2.7</em>
+  <em>celestial-flow 3.2.9</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.7
+- 3.2.9
   - feat:
-    - `TaskInQueue` 中添加 `maxsize` 参数, 用于限制队列最大长度
-    - 在 `graph.connect` 中添加对两个stage输入输出参数类型的检验, 如果不通过, 会有pyright报错
-  - refactor:
-    - 移除对 `tqdm` 的依赖
-      - 根据 `bench\bench_observer.py`, tqdm对轻量级任务影响有限
-      - 这次移除主要是为了完成尽量零第三方库依赖的目标
-    - 将 `observer` 的管理从 `executor` 转到 `metric`
+    - [IMPORTANT] 移除 `stage` 中 `stage_mode`，并添加 `graph_mode`
+      - 破坏性更新
+      - `stage_mode` 可以细粒度的控制每个 `TaskStage` 在图中的模式，但经过多年使用，我认为这种细粒度的控制并无必要，反而无谓的增加理解成本
+      - `graph_mode` 则提供了更粗粒度的控制，用于统一控制所有 `TaskStage` 在图中是串行/多线程/并发运行，适用于大多数场景
+      - 同时完善了 `graph_mode`(serial/thread/async) * `execution_mode`(serial/thread/async) 总共 9 种组合模式
+    - 移除 `schedule_mode`
+      - 破坏性更新
+      - 这个模式带来了许多复杂度，但没有与原先的 `stage_mode / execution_mode` 产生明显的组合优势
+    - 在 `get_graph_analysis` 中添加 `graph_mode`
+      - 这个函数主要用于给web端提供信息
+      - web端代码已经同步修改
+    - 添加新的 `warning` 项，当图不是 dag 且 `graph_mode=serial` 时触发
+    - 移除 `task_executor` 中的参数 `persist_result`
+      - 这是为了简化代码逻辑，同时也使所有任务的最终状态（包括：成功/失败/未执行）都能被统一存储
+    - 将 `task.retry` 事件降级，不再申请单独事件ID，不再在 `lifecycle` 中留痕
+  - reafactor:
+    - 合并 `benchmark` 相关函数对 sync 与 async 两种模式的执行
+      - 性能无差异，代码好看一些
+    - 将原本的 `fallback` 改名为 `lifecycle`
+      - 早在重构原本的 `fail` 时就想起个更恰当的名字，这个版本才实现
+    - 将 `graph.source_lists` 改为 `graph.source_names`
+      - `graph.source_lists` 直接存储节点的引用，而 `graph.source_names` 存储节点的名称
+    - 所有的 `log` / `lifecycle` 文件统一改名为 `flow_log` / `flow_lifecycle`
+    - 删除 `graph` 中的 `out_edges` `in_edges`
+      - 现在由 `OrderGraph` 负责管理边关系
+    - 在 `tarjan_scc` 中使用 DFS 取代原先的递归逻辑
+    - 将 `util_graph` 改名为 `util_order_graph`
+  - fix:
+    - 修复最后一次 report 无法正常上传的问题
+    - 修复 `graph.run` / `graph.run_async` 中 `is_put_signal` 参数没有生效的问题
+  - chore：
+    - 更新文档
 
 更多过往日志可看:
 

{celestialflow-3.2.7 → celestialflow-3.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "celestialflow"
-version = "3.2.7"
+version = "3.2.9"
 description = "A flexible GRAPH-based task orchestration framework."
 readme = "README.md"
 license = { text = "MIT" }
@@ -27,6 +27,9 @@ classifiers = [
 "Homepage" = "https://github.com/Mr-xiaotian/CelestialFlow"
 "Bug Tracker" = "https://github.com/Mr-xiaotian/CelestialFlow/issues"
 
+[tool.uv]
+index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+
 [tool.pytest.ini_options]
 addopts = "-s"
 log_cli = true
@@ -56,6 +59,9 @@ dev = [
     "tqdm",
 ]
 
+[tool.celestialflow]
+log_level = "INFO"
+
 [tool.pyright]
 include = ["src"]
 ignore = ["tests", "**/tests/**", "typings", "demo", "bench", "experiments", "examples", "temp"]

{celestialflow-3.2.7 → celestialflow-3.2.9}/src/celestialflow/__init__.py

@@ -4,6 +4,7 @@
 提供任务图构建、执行调度、实时监控与持久化等核心能力。
 """
 
+from .benchmark.util_benchmark import benchmark_executor, benchmark_graph
 from .funnel import BaseInlet, BaseSpout
 from .graph import (
     TaskChain,
@@ -14,11 +15,12 @@ from .graph import (
     TaskLoop,
     TaskWheel,
 )
-from .observability import BaseObserver
+from .observability import BaseObserver, TaskReporter
 from .persistence.util_sqlite import (
     load_records,
     load_tasks_grouped_by_stage,
 )
+from .runtime.util_format import format_table
 from .runtime.util_hash import make_hashable
 from .runtime.util_types import TerminationSignal
 from .stage import (
@@ -27,8 +29,6 @@ from .stage import (
     TaskSplitter,
     TaskStage,
 )
-from .utils.util_benchmark import benchmark_executor, benchmark_graph
-from .utils.util_format import format_table
 
 __all__ = [
     "BaseInlet",
@@ -41,6 +41,7 @@ __all__ = [
     "TaskGraph",
     "TaskGrid",
     "TaskLoop",
+    "TaskReporter",
     "TaskRouter",
     "TaskSplitter",
     "TaskStage",

celestialflow-3.2.9/src/celestialflow/benchmark/__init__.py

@@ -0,0 +1,6 @@
+# benchmark/__init__.py
+"""CelestialFlow 基准测试与克隆工具模块。
+
+提供执行器/任务图的克隆（clone）与基准测试（benchmark）能力。
+该模块位于依赖链顶层，可依赖其他模块，但不应被其他模块依赖。
+"""

celestialflow-3.2.9/src/celestialflow/benchmark/util_benchmark.py

@@ -0,0 +1,129 @@
+# benchmark/util_benchmark.py
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from ..graph import TaskGraph
+from ..runtime.util_format import format_table
+from ..stage import TaskExecutor
+from .util_clone import clone_executor, clone_graph
+
+type AnyTaskExecutor = TaskExecutor[Any, Any]
+
+
+async def benchmark_executor(
+    sync_executor: AnyTaskExecutor,
+    async_executor: AnyTaskExecutor,
+    task_source: Iterable[Any],
+    execution_modes: list[str] | None = None,
+) -> dict[str, Any]:
+    """
+    对执行器进行基准测试
+
+    :param sync_executor: 同步执行器模板（用于 serial/thread execution_mode）
+    :param async_executor: 异步执行器模板（用于 async execution_mode）
+    :param task_source: 任务源，用于生成任务列表
+    :param execution_modes: 执行模式列表，默认 ["serial", "thread", "async"]
+    :return: 包含测试结果的字典
+    """
+    task_list: list[Any] = list(task_source)
+    execution_modes = execution_modes or ["serial", "thread", "async"]
+
+    use_time: list[list[float]] = []
+    for mode in execution_modes:
+        if mode == "async":
+            cloned_executor = clone_executor(async_executor)
+        else:
+            cloned_executor = clone_executor(sync_executor)
+        cloned_executor.set_execution_mode(mode)
+
+        start = time.perf_counter()
+        if mode == "async":
+            await cloned_executor.run_async(task_list)
+        else:
+            cloned_executor.run(task_list)
+        use_time.append([time.perf_counter() - start])
+
+    use_time_table: str = format_table(use_time, execution_modes, ["Time"])
+    print(f"Use time:\n{use_time_table}\n")
+
+    return {
+        "use_time": use_time,
+        "execution_modes": execution_modes,
+        "table": use_time_table,
+    }
+
+
+async def benchmark_graph(
+    sync_graph: TaskGraph,
+    async_graph: TaskGraph,
+    init_tasks_dict: Mapping[str, Iterable[Any]],
+    graph_modes: list[str] | None = None,
+    execution_modes: list[str] | None = None,
+) -> dict[str, Any]:
+    """
+    对任务图进行基准测试，覆盖 ``graph_mode × execution_mode`` 的全部组合。
+
+    - ``sync_graph`` 用于 ``execution_mode in {"serial", "thread"}`` 的单元格；
+    - ``async_graph`` 用于 ``execution_mode == "async"`` 的单元格；
+    - ``graph_mode`` 决定当前单元格使用 ``run()`` 还是 ``run_async()`` 启动。
+
+    :param sync_graph: 同步任务图模板（用于 serial/thread execution_mode）
+    :param async_graph: 异步任务图模板（用于 async execution_mode）
+    :param init_tasks_dict: 初始任务字典，键为任务标签，值为任务列表
+    :param graph_modes: 要测试的图执行模式列表，默认包括 "serial", "thread", "async"
+    :param execution_modes: 执行模式列表，默认 ["serial", "thread", "async"]
+    :return: 包含测试结果的字典
+    """
+    graph_modes = graph_modes or ["serial", "thread", "async"]
+    execution_modes = execution_modes or ["serial", "thread", "async"]
+
+    base_tasks: dict[str, list[Any]] = {
+        stage_name: list(tasks) for stage_name, tasks in init_tasks_dict.items()
+    }
+
+    test_table_list: list[list[float]] = []
+
+    for graph_mode in graph_modes:
+        time_list: list[float] = []
+
+        for execution_mode in execution_modes:
+            cloned_graph = (
+                clone_graph(async_graph)
+                if execution_mode == "async"
+                else clone_graph(sync_graph)
+            )
+            cloned_graph.set_graph_mode(graph_mode)
+            cloned_graph.set_stage_execution_mode(execution_mode)
+
+            run_tasks: dict[str, Iterable[Any]] = {
+                stage_name: list(tasks) for stage_name, tasks in base_tasks.items()
+            }
+            start_time = time.perf_counter()
+            if graph_mode == "async":
+                await cloned_graph.run_async(run_tasks)
+            else:
+                if execution_mode == "async":
+                    await asyncio.to_thread(cloned_graph.run, run_tasks)
+                else:
+                    cloned_graph.run(run_tasks)
+            time_list.append(time.perf_counter() - start_time)
+
+        test_table_list.append(time_list)
+
+    time_table: str = format_table(
+        test_table_list,
+        graph_modes,
+        execution_modes,
+        "graph/execution",
+    )
+    print(f"Time table:\n{time_table}")
+    return {
+        "use_time": test_table_list,
+        "table": time_table,
+        "graph_modes": graph_modes,
+        "execution_modes": execution_modes,
+    }