Files
CCLite/SPHLite/docs/cclite_worker_protocol.md
2026-07-05 22:48:27 +08:00

3.8 KiB
Raw Permalink Blame History

CCLite Worker Protocol

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

本文记录 SPHLite 侧 CCLite worker 入口的参数、状态、命令和错误语义。当前实现已完成 CLI 解析、能力查询、状态/命令枚举、mock 测试和 Windows shared memory/named event attach 骨架;真实 CCLite 跨进程联调、生产级接触/FSI 仍未完成。

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 参数齐全时,程序会尝试打开 CCLite 创建的 IPC 资源。若资源不存在或平台不支持,会返回受控的 IPC 或 UNSUPPORTED 错误,不退回普通 CLI。

能力查询:

sphlite.exe --cclite-capabilities

--cclite-capabilities 必须单独使用,输出 key=value 能力清单。Windows 构建中 supports_real_ipc=yes 表示 SPHLite 侧 shared memory/named event attach、wait、signal 和 close 路径已进入 self-test;非 Windows 构建仍报告 supports_real_ipc=no。该标志不代表真实外部 CCLite 进程联调或生产级 FSI 已完成。

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 数据块和 contact state 导入;facet load 和 motion boundary 后续补齐
ADVANCE 映射到 sphlite_advance_explicit,dt<=0 时使用稳定时间步估计
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。