Chronaxis用户手册English
API参考 / chronaxis.batch.runner
本页目录相关类型对象导航_new_root参数返回说明异常说明_facts参数返回说明异常说明_cancelled参数返回说明异常说明_report参数返回说明异常说明_run_job参数返回说明异常说明_pause参数说明返回说明异常说明BatchRunnerBatchRunner.__init__BatchRunner.runBatchRunner._run

chronaxis.batch.runner

同时运行多份彼此独立的分析计划，最多启动process_count个任务。每个任务各用自己的状态、资源限额和目录。取消或fail_fast触发后不再启动新任务；已经启动的任务完成清理后退出。process_count限制任务数，并不限制整个Python进程的总内存。

这是模块参考。日常调用先查公开API索引；下划线对象和嵌套函数供维护者查阅。签名来自固定源码，公开类构造签名经实际Python接口核对。

相关类型

AnalysisPlan、AnalysisRunner、BatchJob、BatchJobResult、BatchReport、CleanupHandle、threading.Event、Path

对象导航

对象 用途
_new_root 检查可复用批量目录。
_facts 分别提取计划标识和实际输入标识，写入任务结果。
_cancelled 记录未启动取消。
_report 补齐未启动项。
_run_job 执行一个独立任务并关闭所有资源。
_pause 让出调度CPU等待下一次结果。
BatchRunner 通过有限spawn工作进程执行独立任务；同一任务的连续文件保持原顺序。
BatchRunner.__init__ 配置调度。
BatchRunner.run 运行独立任务，原声明顺序返回报告。
BatchRunner._run 共享派发/清理循环；fast_specs 仅由 fast 校验入口构造，可选 fast_rows 接收汇总所需小行。
导入与重导出来源（展开）
python
from dataclasses import replace
from pathlib import Path
from threading import Event
from time import perf_counter
from ..planning import load_analysis_plan
from ..planning.plan import AnalysisPlan
from ..runner import AnalysisRunner
from ..results.spool import _cleanup_owner
from .._batch_worker import _diagnostics
from .models import BatchJob, BatchJobResult, BatchReport, CleanupHandle

_new_root

检查可复用批量目录。

python
_new_root(value) -> Path

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
value str | pathlib.Path 是 无 位置或关键字。本批任务的根输出目录，可以已有；任务在其中使用带本批时间后缀的独立子目录。

返回说明

绝对Path。

异常说明

类型、不可用目录或受保护路径错误。

返回类型：Path。

源码：src/chronaxis/batch/runner.py:24（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

_facts

分别提取计划标识和实际输入标识，写入任务结果。

python
_facts(job, plan=None) -> dict

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
job BatchJob 是 无 位置或关键字。当前批量任务声明，包含job_id、plan路径及所用实现。
plan AnalysisPlan | None 否 None 位置或关键字。已成功加载的分析计划；加载失败或任务尚未启动时为None。

返回说明

字段dict。

异常说明

无。

返回类型：dict。

源码：src/chronaxis/batch/runner.py:30（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

_cancelled

记录未启动取消。

python
_cancelled(job, reason) -> BatchJobResult

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
job BatchJob 是 无 位置或关键字。需要标记为取消的任务声明，保留其原job_id与计划路径。
reason str 是 无 位置或关键字。取消原因，写入该任务结果，便于区分主动取消和前序失败后停止。

返回说明

取消结果。

异常说明

无，不读取计划。

返回类型：BatchJobResult。

源码：src/chronaxis/batch/runner.py:41（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

_report

补齐未启动项。

python
_report(root, jobs, results, process_count, fail_fast, cancelled, label, reason) -> BatchReport

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
root pathlib.Path 是 无 位置或关键字。本批已经建立的根输出目录；批次清单在此发布。
jobs BatchJob 是 无 位置或关键字。按声明顺序排列的BatchJob序列。
results list[BatchJobResult | None] 是 无 位置或关键字。与jobs按位置一一对应的结果列表；尚未启动的任务为None，汇总时补成取消结果。
process_count int 是 无 位置或关键字。实际允许的最大并发任务数，正整数。
fail_fast bool 是 无 位置或关键字。发生失败后是否停止启动新任务的布尔开关。
cancelled bool 是 无 位置或关键字。本次调度是否已收到取消请求，决定批次汇总的取消状态。
label str 是 无 位置或关键字。实际产出设备标签字符串，传入报告。
reason str 是 无 位置或关键字。未启动任务的取消原因文字。

返回说明

完整报告。

异常说明

模型错误。

返回类型：BatchReport。

源码：src/chronaxis/batch/runner.py:46（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

_run_job

执行一个独立任务并关闭所有资源。

python
_run_job(job, directory, backend, stop, cancel) -> BatchJobResult

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
job BatchJob 是 无 位置或关键字。一个独立任务，含任务id和计划对象或计划文件路径。
directory Path 是 无 位置或关键字。本任务独占的新子目录；内部work存暂存，output存正式结果。
backend str 是 无 位置或关键字。"reference"使用独立参考计算；"numpy"使用NumPy数组计算。须明确选择一种。
stop threading.Event 是 无 位置或关键字。批量调度器的停止标记；发现失败且启用fail_fast后设置，用于阻止启动后续任务。
cancel threading.Event | None 是 无 位置或关键字。调用者提供的取消标记；为None表示未提供。它不强行终止已经运行的分析。

返回说明

含实际发布和身份的最终结果；恢复失败保最高owner，不把异常栈留在结果中。

异常说明

普通分析/发布/取消转换成该任务结果；无法构造结果的内部错误交由调度器收尾。

返回类型：BatchJobResult。

源码：src/chronaxis/batch/runner.py:55（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

_pause

让出调度CPU等待下一次结果。

python
_pause()

参数：无显式参数。

参数说明

无。

返回说明

None。

异常说明

主进程取消。

源码：src/chronaxis/batch/runner.py:103（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

BatchRunner

通过有限spawn工作进程执行独立任务；同一任务的连续文件保持原顺序。

python
BatchRunner(process_count=1, *, fail_fast=False, backend=None)

源码：src/chronaxis/batch/runner.py:108（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

BatchRunner.__init__

配置调度。

python
BatchRunner.__init__(process_count=1, *, fail_fast=False, backend=None)

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
process_count int 否 1 位置或关键字。控制最多启动几个分析工作进程。填正整数，例如4；默认1。任务少于该值时按任务数启动，空批次不启动。此数量不包含调度主进程和CAN读取子进程。
fail_fast bool 否 False 仅关键字。False时某任务失败仍继续尝试后续任务；True时发现失败后停止启动新任务，但等待已启动任务收尾。
backend str | None 否 None 仅关键字。auto按整份计划选择reference或numpy，不预读或试跑；reference和numpy固定使用对应数值实现。None沿用计划设置。详见运行参数。

返回说明

None。初始化调度选项；调用BatchRunner(...)才创建并取得实例。此时不启动工作进程或读取输入。

异常说明

类型、范围或计算后端无效。构造时不读取业务数据，也不启动工作进程。

本函数直接报告的具体错误：

  • ValueError：process_count需要正原生int。
  • TypeError：fail_fast需要bool。

源码：src/chronaxis/batch/runner.py:111（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

BatchRunner.run

运行独立任务，原声明顺序返回报告。

python
BatchRunner.run(jobs, output_dir, *, cancel_event=None, device_label='pending') -> BatchReport

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
jobs tuple 是 无 位置或关键字。提供BatchJob元组，例如load_batch_plan("batch.yaml").jobs；每项含独立分析的ID与计划，顺序决定报告排列。
output_dir str | Path 是 无 位置或关键字。可重复使用的批量结果目录；任务子目录带本批时间后缀，已有结果保持。实际路径从报告读取。
cancel_event threading.Event | None 否 None 仅关键字。可选取消标记；None表示没有。其他线程调用set()后停止派发新任务，正在执行的任务继续收尾。
device_label str 否 'pending' 仅关键字。产出记录的设备标签，接受任意非空文本，如lab-pc或试验台一号；省略时使用pending。标签不参与计算，也不根据文件路径猜测。

返回说明

BatchReport；jobs各项的manifest_path为实际完成清单。本方法不写批量报告，report_path为None；close可重试未完成清理。

异常说明

声明/路径错误在创建工作进程前拒绝；工作进程调度器等基础设施错误收尾后传播，产生报告时附batch_report。若Ctrl+C发生于worker构造且清理仍未完成，原KeyboardInterrupt附batch_worker_cleanup_owner传播；这个未构造完的worker可能不在报告任务中，需要保留恢复对象并重试close。已清理Ctrl+C仍按正常取消流程返回报告。

本函数直接报告的具体错误：

  • TypeError：批量任务需要BatchJob tuple。
  • ValueError：批量job_id不能重复，大小写冲突也拒绝。
  • TypeError：cancel_event需要threading.Event。
  • ValueError：device_label需要非空文本。

副作用说明

启动最多process_count个工作进程，每任务独立发布；取消只阻止未派发任务。

返回类型：BatchReport。

源码：src/chronaxis/batch/runner.py:124（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

BatchRunner._run

共享派发/清理循环；fast_specs 仅由 fast 校验入口构造，可选 fast_rows 接收汇总所需小行。

python
BatchRunner._run(jobs, output_dir, *, cancel_event, device_label, fast_specs=None, fast_rows=None)

参数

名称 数据类型 必填 省略时的值 用途、取值和效果
jobs tuple[BatchJob, ...] 是 无 位置或关键字。按配置顺序派发的独立任务。
output_dir str | Path 是 无 位置或关键字。本批次报告和各文件发布目录的父路径。
cancel_event threading.Event | None 是 无 仅关键字。已设置时取消本次操作，省略时按调用方的正常生命周期运行。
device_label str 是 无 仅关键字。报告标记所用设备的来源名称。
fast_specs dict | None 否 None 仅关键字。任务名到文件级计算参数的映射，启用 fast 时传入。
fast_rows dict | None 否 None 仅关键字。请求总量时收集各任务未舍入行，按任务名存放。

源码：src/chronaxis/batch/runner.py:134（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

Chronaxis 用户手册 · 离线阅读