Transaction

当发出去一个异步请求，支持在后来收到回复消息时自动执行回调函数，如果超时没有收到消息也将触发回调函数的执行。

也支持同步请求，在收到回复之前阻塞等待，直到返回所收到的回复消息，或者超时。

支持在其他线程中执行数据接收。

创建和删除上下文

sync_ctx_t  create_sync_ctx();

void delete_sync_ctx(sync_ctx_t ctx);

创建异步Transaction

transaction_id_t bh_transaction_new(sync_ctx_t sync_ctx, 
        bh_async_callback cb,   // 回调函数
        void* ctx_data,         // 用户数据，会作为参数user_data被传递给回调函数
        uint32_t timeout_ms);   // 超时毫秒数

返回transaction_id_t类型数据，是所创建的Transaction的唯一整数标识。

回调函数原型如下，在调用bh_feed_response过程中或者超时：

typedef int (*bh_async_callback) (void * user_data, void * response, int len,
     transaction_resp_fmt_t format);

Feed response

给参数id所代表的异步Transaction输入Response，触发其回调函数。

常用的情况是发送网络请求中包含bh_transaction_new()返回的transaction_id， 对方回复的消息也包含该ID，接收的线程使用ID的数值调用bh_feed_response()。 也可用于其他场景。

bool bh_feed_response(sync_ctx_t sync_ctx, 
        transaction_id_t id, 
        void * response,  
        uint32_t resp_buffer_size,  // 
        transaction_resp_fmt_t format);

• id： transaction ID
• response：指向response的数据
• resp_buffer_size：0表示response为由format所提示的自定义数据结构， >0: response指向的是一个长度resp_buffer_size为的buffer。

提示

被触发的回调函数将在bh_feed_response()函数内部被执行，response参数将被传递给回调函数。

如果需要保证数据在某个特定的线程中执行，回调函数需要克隆response数据然后传递到其他线程。

检查超时

超时的异步Transaction会被自动调用回调函数，而且response参数为NULL。

uint32_t bh_handle_expired_trans(sync_ctx_t sync_ctx);

返回值：最近一个超时毫秒数。

阻塞等待Transaction

等待者使用bh_gen_id()创建的transaction id发送请求，然后调用bh_wait_response阻塞等待response。另外一个线程从网络收到response数据后，调用bh_transaction_handover_response将把收到的response数据转交给等待者， 然后bh_wait_response将立即返回该数据给调用者。

transaction_id_t bh_gen_id(sync_ctx_t  ctx);

void* bh_wait_response(sync_ctx_t sync_ctx, transaction_id_t id, int * len, int * fmt, uint32_t timeout_ms);

bool bh_transaction_handover_response(sync_ctx_t  sync_ctx, 
        transaction_id_t id, 
        void ** response,   // 在成功触发Transaction返回后，该参数指向NULL
        uint8_t format);

提示

调用bh_transaction_handover_response()时，response参数必须指向从堆上分配的数据，该数据将被转给调用bh_wait_response()的线程。