Files
SPHLite/docs/cclite_worker_protocol.md
T
2026-07-05 17:00:13 +08:00

3.2 KiB
Raw Blame History

CCLite Worker Protocol

文档状态:0.8.x worker adapter 骨架说明

本文记录 SPHLite 侧 CCLite worker 入口的参数、状态、命令和错误语义。当前实现只完成 CLI 解析、纯逻辑状态/命令枚举和测试;Windows shared memory、named event 和真实 CCLite 联调仍未实现。

1. CLI 参数

启用 worker:

sphlite.exe --cclite-worker --solver-id SPH --case sphlite.inp --ipc-name <name>

参数语义:

参数 必填 默认值 含义
--cclite-worker 是 无 进入 CCLite worker 模式
--solver-id 否 SPH CCLite 侧识别的求解器 id
--case 是 无 SPHLite 输入文件路径
--ipc-name 是 无 CCLite 分配的 IPC 基础名称
--command-block 否 空 command block 名称
--data-prefix 否 空 data block 名称前缀
--log 否 sphlite_cclite_worker.log worker 日志路径
--timeout-ms 否 30000 等待命令超时时间,必须为正整数
--worker-id 否 sphlite worker 实例 id

--cclite-worker 与普通 CLI 参数 --run、--check、--output、--version 冲突。未启用 worker 时,普通 CLI 行为保持:

sphlite.exe model.inp
sphlite.exe model.inp --check
sphlite.exe model.inp --run --output result

当前所有必填 worker 参数齐全时,程序会返回受控的 UNSUPPORTED,表示 IPC 阶段尚未实现。

2. 状态枚举

状态 含义
CREATED worker 对象已创建但未 ready
READY worker 可接收命令
RUNNING 命令执行中,预留给真实 IPC 主循环
DONE 当前命令已完成并可写 ack
ERROR 当前命令失败或进入错误态
STOPPED 收到 STOP 后停止

3. 命令枚举

命令 处理流程
INIT 清理 worker 侧状态;允许从 ERROR 恢复到可继续状态
READ_INPUT 后续映射到 sphlite_read_inp
BUILD_MODEL 后续映射到 sphlite_build_model
EXPORT_INTERFACE 后续映射到 coupling region count/info、particle export 和 facet export
IMPORT_LOADS 后续映射到 particle force、facet pressure/traction/resultant、contact state 和 motion boundary 导入
ADVANCE 后续映射到 sphlite_advance_explicit 或 worker 控制的子步循环
WRITE_OUTPUT 后续映射到 sphlite_write_output
STOP 写入完成状态后退出 worker

未知命令进入 ERROR,错误码为 UNKNOWN_COMMAND。

4. Ack 和错误

ack 序号只接受严格递增的 command sequence:

command_sequence > last_ack_sequence

错误码:

错误码 含义
OK 命令成功
ARGUMENT CLI 参数或内部参数错误
CONFLICT 当前状态与命令冲突
UNSUPPORTED 入口已识别,但当前能力未实现
TIMEOUT 等待命令超时
IPC IPC 打开、读取、写入或 signal/wait 失败
UNKNOWN_COMMAND command id 未识别
INTERNAL 其他内部错误

超时处理固定进入 ERROR,错误码为 TIMEOUT。已经 STOPPED 后收到除进程退出外的命令,固定保持 STOPPED 并返回 CONFLICT。