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

87 lines
3.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CCLite Worker Protocol
文档状态:0.8.x worker adapter 骨架说明
本文记录 SPHLite 侧 CCLite worker 入口的参数、状态、命令和错误语义。当前实现只完成 CLI 解析、纯逻辑状态/命令枚举和测试;Windows shared memory、named event 和真实 CCLite 联调仍未实现。
## 1. CLI 参数
启用 worker:
```text
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 行为保持:
```text
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:
```text
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`。