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

95 lines
3.8 KiB
Markdown
Raw Permalink 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 解析、能力查询、状态/命令枚举、mock 测试和 Windows shared memory/named event attach 骨架;真实 CCLite 跨进程联调、生产级接触/FSI 仍未完成。
## 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 参数齐全时,程序会尝试打开 CCLite 创建的 IPC 资源。若资源不存在或平台不支持,会返回受控的 `IPC` 或 `UNSUPPORTED` 错误,不退回普通 CLI。
能力查询:
```text
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:
```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`。