线程模型

本文介绍交易API的线程模型。理解线程模型有助于正确使用API接口、避免死锁和数据竞争。

线程概览

交易API运行时涉及以下线程：

线程	说明
用户线程（可多个）	用户自己的业务线程，通常在此调用API请求接口向柜台发送上行请求
登录及查询回调线程	API内部线程，接收柜台下行消息，触发登录响应、查询响应等回调
消息推送线程	API内部线程，接收柜台下行消息，触发订阅后的交易消息推送回调（回报、订单簿变动等）
超时通知线程	API内部线程，请求超时、委托超时没有收到任何回报时触发相应登录响应、查询响应、委托超时等回调

用户线程

用户线程是用户自己创建的业务线程，可以有多个。API的请求接口可以在任意线程中调用（包括用户线程和回调线程），常用接口如下：

• x1::XLTTradeApi::create — 创建实例
• x1::XLTTradeApi::initialize — 初始化
• x1::XLTTradeApi::login / x1::XLTTradeApi::logout — 登录/登出
• x1::XLTTradeApi::subscribe_trade_message / x1::XLTTradeApi::rebuild_trade_message — 订阅/重推
• x1::XLTTradeApi::insert_order / x1::XLTTradeApi::cancel_order — 下单/撤单
• x1::XLTTradeApi::query_assets / x1::XLTTradeApi::query_positions 等查询接口
• x1::XLTTradeApi::get_init_assets / x1::XLTTradeApi::get_init_positions 等同步获取接口

下单/撤单性能建议：

• x1::XLTTradeApi::insert_order 和 x1::XLTTradeApi::cancel_order 为线程本地发送，如果在用户线程中调用，建议该线程进行绑核以获得最优性能。
• 线程中首次调用下单/撤单前，建议先调用 x1::XLTTradeApi::init_local_send 预分配本地发送资源，避免首次发送时的额外延迟。

登录及查询回调线程

此线程由API内部管理，负责触发以下回调：

• x1::XLTTradeSpi::on_login — 登录响应
• x1::XLTTradeSpi::on_auth_trade — 认证响应
• x1::XLTTradeSpi::on_disconnect — 断线通知
• x1::XLTTradeSpi::on_subscribe_trade_message — 订阅响应
• x1::XLTTradeSpi::on_rebuild_trade_message — 重推响应
• x1::XLTTradeSpi::on_query_assets — 资金查询响应
• x1::XLTTradeSpi::on_query_positions — 持仓查询响应
• x1::XLTTradeSpi::on_query_orders — 订单查询响应
• x1::XLTTradeSpi::on_query_orders_by_page — 分页订单查询响应
• x1::XLTTradeSpi::on_query_trades — 成交查询响应
• x1::XLTTradeSpi::on_query_init_assets — 初始资产查询响应
• x1::XLTTradeSpi::on_query_init_positions — 初始持仓查询响应
• x1::XLTTradeSpi::on_query_trade_account_info — 交易账号信息查询响应

注意事项：

• 回调函数需要尽快返回，长时间阻塞会导致后续消息堆积，严重时可能触发断线。

消息推送线程

此线程由API内部管理，负责触发订阅后的交易消息推送回调，包括：

委托回报消息（REPORT）：

• x1::XLTTradeSpi::on_order_response — 申报成功
• x1::XLTTradeSpi::on_cancel_response — 撤单成功
• x1::XLTTradeSpi::on_trade_report — 成交回报
• x1::XLTTradeSpi::on_order_error_response — 委托失败
• x1::XLTTradeSpi::on_order_end — 订单结束

原始报文消息（RAW_REPORT）：

• x1::XLTTradeSpi::on_raw_report — 交易所原始报文

订单簿消息（ORDER_BOOK）：

• x1::XLTTradeSpi::on_order_book_insert — 新订单明细
• x1::XLTTradeSpi::on_order_book_update — 订单变动明细
• x1::XLTTradeSpi::on_order_book_error — 订单错误明细
• x1::XLTTradeSpi::on_asset — 资金变动明细
• x1::XLTTradeSpi::on_position — 持仓变动明细

资金划拨消息（任意订阅类型均会推送）：

• x1::XLTTradeSpi::on_counter_fund_transfer_request — 主柜资金划拨请求
• x1::XLTTradeSpi::on_counter_fund_transfer_result — 主柜资金划拨结果
• x1::XLTTradeSpi::on_cluster_fund_transfer_request — 双中心资金划拨请求
• x1::XLTTradeSpi::on_cluster_fund_transfer_result — 双中心资金划拨结果

注意事项：

• 推送回调需要尽快返回，否则会阻塞后续消息推送，严重时可能触发断线。
• 推送回调与登录/查询回调运行在不同线程中，用户在回调实现中访问共享数据时需要注意线程安全。

线程安全总结

场景	建议
API请求接口的调用线程	可在任意线程中调用（用户线程或回调线程均可）
下单/撤单性能优化	建议调用线程进行绑核，线程中首次调用前调用 x1::XLTTradeApi::init_local_send
在回调中访问共享数据	推送回调与登录/查询回调运行在不同线程中，访问共享数据时需加锁保护或使用无锁结构