Files

95 lines
3.8 KiB
Markdown
Raw Permalink Normal View History

2026-07-05 17:00:13 +08:00
# CCLite Worker Protocol
文档状态:0.8.x worker adapter 骨架说明
2026-07-05 21:41:34 +08:00
本文记录 SPHLite 侧 CCLite worker 入口的参数、状态、命令和错误语义。当前实现已完成 CLI 解析、能力查询、状态/命令枚举、mock 测试和 Windows shared memory/named event attach 骨架;真实 CCLite 跨进程联调、生产级接触/FSI 仍未完成。
2026-07-05 17:00:13 +08:00
## 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
```
2026-07-05 21:41:34 +08:00
当前所有必填 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 已完成。
2026-07-05 17:00:13 +08:00
## 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` |
2026-07-05 21:41:34 +08:00
| `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` |
2026-07-05 17:00:13 +08:00
| `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`。