推理池 API

提交、等待、关闭。打开见 打开。C++ 与 C 共用同一份 C ABI。

调度

darra_sched_set_gpu_slots()

void darra_sched_set_gpu_slots(int32_t gpu_device, int32_t slots);

同一 GPU 同时 InferImage 上限（张）。device 对应 gpu_device。slots = 0（默认）= 不限制。>0 时按 weight 份额排队：某 owner 最多同时跑 max(1, slots * weight / 100) 路，全局仍不超过 slots。这不是 CUDA SM 占用百分比，是并发推理槽。

参数:

• gpu_device (int32_t) — 卡号，与 darra_session_options.gpu_device 相同
• slots (int32_t) — 0 = 不限制；>0 = 该卡同时 Infer 上限

示例:

darra_sched_set_gpu_slots(0, 4);

提交

darra_pool_submit()

int32_t darra_pool_submit(darra_pool* pool,
                          const uint8_t* image_bytes,
                          size_t len,
                          const darra_image_desc* desc,
                          uint64_t* out_ticket);

提交一张图。成功时 *out_ticket > 0。图像字节会被拷走，调用方可立即释放入参。可多线程 submit。

参数:

• pool (darra_pool*) — 已打开的池
• image_bytes (const uint8_t*) — 编码字节流或裸缓冲，语义同 darra_session_infer_image
• len (size_t) — 字节数
• desc (const darra_image_desc*) — 图像描述；desc->size 必填。结构见 类型
• out_ticket (uint64_t*) — 成功时票号 > 0

返回值:

• int32_t — DARRA_OK 成功；DARRA_BUSY（OVERFLOW_FAIL 且队列满）；DARRA_INTERNAL（契约违反）

示例:

darra_image_desc desc{};
desc.size = sizeof(desc);
desc.format = DARRA_IMAGE_AUTO;

uint64_t ticket = 0;
int32_t rc = darra_pool_submit(pool, jpg.data(), jpg.size(), &desc, &ticket);
if (rc == DARRA_BUSY) {
    // OVERFLOW_FAIL：队列满
}

等待

darra_pool_wait()

int32_t darra_pool_wait(darra_pool* pool,
                        uint64_t ticket,
                        char** out_results_json);

等待一张图的 JSON。SDK 分配，用完 darra_string_free。被 DROP_OLDEST 挤掉的票返回 DARRA_BUSY。

参数:

• pool (darra_pool*) — 已打开的池
• ticket (uint64_t) — submit 拿到的票
• out_results_json (char**) — 结果 JSON，SDK 分配

返回值:

• int32_t — DARRA_OK 成功；DARRA_BUSY（票被 DROP_OLDEST 挤掉）；其它同 darra_session_infer_image

示例:

char* json = nullptr;
int32_t rc = darra_pool_wait(pool, ticket, &json);
if (rc == DARRA_OK) {
    std::printf("%s\n", json);
    darra_string_free(json);
}

darra_pool_try_wait()

int32_t darra_pool_try_wait(darra_pool* pool,
                            uint64_t ticket,
                            char** out_results_json);

非阻塞。还没好返回 DARRA_BUSY（message 说明仍在队列 / 推理）。被挤掉同样 DARRA_BUSY。

参数:

• pool (darra_pool*) — 已打开的池
• ticket (uint64_t) — submit 拿到的票
• out_results_json (char**) — 已完成时结果 JSON，SDK 分配

返回值:

• int32_t — DARRA_OK 已完成；DARRA_BUSY 还没好或已被挤掉

示例:

char* json = nullptr;
int32_t rc = darra_pool_try_wait(pool, ticket, &json);
if (rc == DARRA_BUSY) {
    // 仍在队列或推理
}

关闭

darra_pool_close()

void darra_pool_close(darra_pool* pool);

关闭池：拒新任务、等在飞 Infer 结束、关全部会话。禁止与 submit / wait 并发。nullptr 安全。close 后句柄失效，再用 = 未定义行为。

参数:

• pool (darra_pool*) — 要关闭的池；nullptr 为 no-op

示例:

darra_pool_close(pool);
pool = nullptr;

完整示例

#include "darra_ai.h"
#include <cstdio>
#include <fstream>
#include <vector>

int main() {
    darra_pool_options opt{};
    opt.size = sizeof(opt);
    opt.max_workers = 2;
    opt.queue_capacity = 64;
    opt.overflow = DARRA_OVERFLOW_FAIL;
    opt.worker.size = sizeof(opt.worker);
    opt.worker.unique = 1;
    opt.worker.gpu_device = 0;

    darra_pool* pool = nullptr;
    int32_t rc = darra_pool_open("model.darmodel", nullptr, nullptr, nullptr, &opt, &pool);
    if (rc != DARRA_OK) {
        darra_error_t err{};
        err.size = sizeof(err);
        darra_last_error(&err);
        return static_cast<int>(rc);
    }

    std::ifstream in("photo.jpg", std::ios::binary);
    std::vector<uint8_t> jpg((std::istreambuf_iterator<char>(in)),
                             std::istreambuf_iterator<char>());

    darra_image_desc desc{};
    desc.size = sizeof(desc);
    desc.format = DARRA_IMAGE_AUTO;

    uint64_t ticket = 0;
    rc = darra_pool_submit(pool, jpg.data(), jpg.size(), &desc, &ticket);
    if (rc == DARRA_BUSY) {
        darra_pool_close(pool);
        return static_cast<int>(rc);
    }

    char* json = nullptr;
    rc = darra_pool_wait(pool, ticket, &json);
    if (rc == DARRA_OK) {
        std::printf("%s\n", json);
        darra_string_free(json);
    }
    darra_pool_close(pool);
    return static_cast<int>(rc);
}