查询 (Get / Query)

查询是请求-响应式交互的客户端一侧：向一个 key expression 发起一次 Get，应答器返回零个或多个回复。回复通过回复接收通道（onepath_reply_rx_t）取回，可阻塞或非阻塞接收。应答器一侧见 Responder，持久请求器见 Requester。

onepath_get

int onepath_get(onepath_session_t s, const char *key, const char *parameters,
              onepath_reply_rx_t *out, const onepath_get_opts_t *opts);

发起一次性查询，返回回复接收通道。

• 参数：
  • s — 会话句柄
  • key — 查询的 key expression
  • parameters — 查询参数字符串，传 NULL 或 "" 表示无参数
  • out — 输出回复接收通道句柄
  • opts — 查询选项，传 NULL 使用默认值（超时 5000ms，见 onepath_get_opts_t）
• 返回值：ONEPATH_OK 成功
• 注意：使用完毕后必须调用 onepath_reply_rx_destroy() 销毁接收通道

多应答者投票

默认 target 只路由到最佳匹配的应答者、consolidation 会合并同键应答。要收集全部应答者的每一份回复（如多副本投票），须在 opts 中把 target 设为 ONEPATH_QUERY_TARGET_ALL、consolidation 设为 ONEPATH_CONSOLIDATION_NONE。常量见 工具与常量。

onepath_reply_recv

int onepath_reply_recv(onepath_reply_rx_t rx, onepath_reply_t *out);

从回复通道阻塞接收一个回复。

• 参数：rx — 回复接收通道句柄；out — 输出回复数据
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_CLOSED 所有回复已接收完毕
• 注意：收到的回复使用完毕后必须调用 onepath_reply_release() 释放

onepath_reply_try_recv

int onepath_reply_try_recv(onepath_reply_rx_t rx, onepath_reply_t *out);

从回复通道非阻塞接收一个回复。

• 参数：rx — 回复接收通道句柄；out — 输出回复数据
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_TIMEOUT 暂无数据，ONEPATH_ERR_CLOSED 通道关闭
• 注意：收到的回复使用完毕后必须调用 onepath_reply_release() 释放

onepath_reply_release

void onepath_reply_release(onepath_reply_t *reply);

释放通过通道接收到的回复。

• 参数：reply — 回复指针

onepath_reply_rx_destroy

void onepath_reply_rx_destroy(onepath_reply_rx_t rx);

销毁回复接收通道。

• 参数：rx — 回复接收通道句柄

示例

onepath_reply_rx_t rx;
if (onepath_get(s, "demo/service/**", NULL, &rx, NULL) == ONEPATH_OK) {
    onepath_reply_t reply;
    while (onepath_reply_recv(rx, &reply) == ONEPATH_OK) {
        if (reply.is_ok) {
            printf("回复 [%s]: %.*s\n",
                   reply.key, (int)reply.data_len, (const char *)reply.data);
        } else {
            printf("错误回复: %.*s\n",
                   (int)reply.err_msg_len, reply.err_msg);
        }
        onepath_reply_release(&reply);   /* 必须释放 */
    }
    onepath_reply_rx_destroy(rx);        /* 必须销毁通道 */
}

回复数据结构见 onepath_reply_t。