跳到主要内容

提交与等待

突发：一次 submit 多张。queueCapacity 必须 ≥ 突发量，或 overflow=BLOCK。流式：每毫秒一张。GPU 若 5ms/张，队列会积压——必须选 overflow。

队列满时：

  • FAIL — submit 立即失败，码 19（DARRA_BUSY）
  • BLOCK — submit 等到有空位
  • DROP_OLDEST — 丢掉最旧未开跑任务；被挤掉的票 waitFor 得码 19

码 19 的 Java 形态见 错误处理。

图像字节会被拷走，调用方可立即释放入参。可多线程 submit。close() 禁止与 submit / waitFor 并发。

方法​

submit(byte[] imageBytes, ImageDesc desc)​

public long submit(byte[] imageBytes, ImageDesc desc)

提交一张图。返回 ticket（按无符号 64 位解释）。ticket == 0 抛 InternalException。

参数:

  • imageBytes (byte[]) — AUTO/ENCODED = 编码文件字节；裸缓冲 = 像素内存。null = InternalException
  • desc (ImageDesc) — 图像描述。null = InternalException

返回值:

  • long — ticket，交给 waitFor / tryWait

示例:

long ticket = pool.submit(jpg, ImageDesc.auto());

submitAsync(byte[] imageBytes, ImageDesc desc)​

public CompletableFuture<String> submitAsync(byte[] imageBytes, ImageDesc desc)

异步糖：submit + waitFor。图像会被拷走。失败以 AiException 完成。

参数:

  • imageBytes (byte[]) — 图像字节
  • desc (ImageDesc) — 图像描述

返回值:

  • CompletableFuture<String> — 结果 JSON 的 future

示例:

String json = pool.submitAsync(jpg, ImageDesc.auto()).join();

waitFor(long ticket)​

public String waitFor(long ticket)

等待结果 JSON。对齐 C darra_pool_wait。被 InferOverflow.DROP_OLDEST 挤掉的票抛码 19。

参数:

  • ticket (long) — submit 返回值

返回值:

  • String — 结果 JSON。Java 侧拷贝，无需释放

示例:

long ticket = pool.submit(jpg, ImageDesc.auto());
String json = pool.waitFor(ticket);

tryWait(long ticket)​

public String tryWait(long ticket)

非阻塞。还没好抛码 19（message 说明仍在队列 / 推理）。

参数:

  • ticket (long) — submit 返回值

返回值:

  • String — 结果 JSON

示例:

try {
    String json = pool.tryWait(ticket);
} catch (AiException ex) {
    if (ex.getCode() == 19) {
        return;
    }
    throw ex;
}

close()​

@Override
public void close()

关闭池：拒新任务、等在飞 Infer 结束、关全部会话。NULL / 重复关闭安全。禁止与 submit / waitFor 并发。

示例:

try (AiInferPool pool = AiInferPool.openPlain("model.onnx", null, null)) {
    long t = pool.submit(jpg, ImageDesc.auto());
    String json = pool.waitFor(t);
}

完整示例​

import xyz.darra.ai.*;

InferPoolOptions opt = InferPoolOptions.empty()
        .maxWorkers(2)
        .queueCapacity(128)
        .overflow(InferOverflow.DROP_OLDEST)
        .worker(SessionOptions.empty().gpuDevice(0))
        .weight(100);
GpuScheduler.setGpuSlots(0, 4);
try (AiInferPool pool = AiInferPool.openPlain("yolov8n.onnx", "onnx-cuda", opt)) {
    long ticket = pool.submit(frame, ImageDesc.bgr888(1920, 1080));
    String json = pool.waitFor(ticket);
} catch (AiException ex) {
    if (ex.getCode() == 19) {
        System.err.println(ex.getHint());
        return;
    }
    System.err.println("[" + ex.getCode() + "] " + ex.getMessage());
    System.err.println("建议: " + ex.getHint());
}