跳到主要内容

会话

一个 darra_session* = 一份已加载模型 + 一个 Provider。多模型或多份同模型 = 多会话，API 完全相同。绑定不得另造「模型组 / 全局引擎」语义。

相关页面

功能概览​

页面函数说明
打开darra_session_open / open_plain / open_ex / open_plain_ex打开加密容器或明文模型
APIdarra_session_meta_json / darra_session_close读元信息、关闭句柄
推理darra_session_infer_image每次一张图；连续帧循环调用

句柄​

typedef struct darra_session darra_session;

不透明句柄：定义只在 Core 内部，绑定侧永远只持有指针。一个句柄 = 一份已验票 / 已解密的模型 + 一个已选定的运行时 Provider。

darra_session_close 之后句柄失效，再用 = 未定义行为。NULL 关闭是安全的。

流程​

darra_session_open / open_plain / *_ex
        │  验票 / 解密 / 按 PayloadKind × 硬件选 Provider
        │  对应包未装 → 内部 darra_runtime_ensure（无进度，可能阻塞下载）
        ▼
darra_session*
        │
        ├─ darra_session_meta_json      读容器头 / 明文探测（微秒级）
        │
        └─ darra_session_infer_image    每次一张图
              ▲                         连续帧：循环调用本函数
              └── 编码图 / 裸缓冲（RGB888 / BGR888 / GRAY8 / RGBA8888）
        │
        ▼
darra_session_close                     释放；禁止与在飞调用并发

第一次 open 才有打开成本；之后每帧反复 darra_session_infer_image，不要每张图重新打开。

打开规则​

打开时按 PayloadKind × 硬件 × prefer_provider 选 Provider。指名但不可用（无硬件 / 驱动过旧 / 平台不支持）= fail-closed，绝不静默降级。

  • Paddle 是运行时载荷（PayloadKind=paddle）。明文可接 .pdmodel（同目录须有 .pdiparams）或含二者的目录。
  • .pt / .pth 仍拒，收到即 DARRA_UNSUPPORTED_PAYLOAD（先转 ONNX）。
  • Windows 无 RKNN。 rknn 载荷只在 linux-arm64 板端运行；Windows 收到即 DARRA_UNSUPPORTED_PAYLOAD。指名 edge-rknn 返回 DARRA_UNSUPPORTED_PLATFORM。
  • darra_session_options 只约束本会话推理线程池。禁止改 Windows ReservedCpuSets，禁止动 PLC 隔离核。

线程约定​

函数线程安全备注
darra_session_open / open_plain / open_ex / open_plain_ex是各开各的会话可并发；缺包时内部 ensure 走同一把进程锁
darra_session_meta_json是只读会话内不可变数据
darra_session_infer_image同会话可并发吞吐扩展推荐每线程一个会话
darra_session_close仅在不与其它调用并发时close 后句柄失效，再用 = 未定义行为

不同会话互不干扰，可并发。