异步接口使用指南

异步接口使用指南

头文件：wmpf/operation.h。

SDK 的接口存在大量异步操作。如果看到一个函数的返回值类型为wx_operation_t，则说明此函数是一个异步函数，需要在合适的时机调用如下任一函数以等待来异步执行的结果：

• wx_operation_wait()：同步阻塞式等待。支持设置超时时间。
• wx_operation_await()：异步等待，不会阻塞当前线程。支持设置回调函数。

如果不关心异步操作的结果，可以调用如下函数释放wx_operation_t对象。

• wx_operation_destroy()：主动销毁wx_operation_t对象。异步操作会继续执行。

如果想取消一个异步操作，可以调用如下函数：

• wx_operation_cancel()：取消异步操作。

请特别注意wx_operation_t对象的生命周期，以免造成内存泄漏：

• 调用 wx_operation_wait 或 wx_operation_await 函数直至异步调用结束，那么wx_operation_t对象会被自动回收。
• 如果调用 wx_operation_wait 超时，可以重新调用 wx_operation_wait函数以继续等待，或者调用wx_operation_cancel()主动结束此次异步调用。cancel 后wx_operation_t对象亦会被自动回收。
• 也可以手动调用wx_operation_destroy()销毁 operation 对象，这种情况下异步操作还会继续进行，但是将不会收到异步调用的结果。

1. 同步等待

同步阻塞当前线程，直到操作完成或超时。

• 如果操作完成（包括正常返回和接口异常的情况），wx_operation_t 将被自动释放。

• 如果异步操作没有在指定时间内完成，返回

  WXERROR_TIMEOUT
  

  。可以有以下选择：

  • 重新调用 wx_operation_wait() 继续等待；
  • 调用 wx_operation_cancel() 取消异步调用；
  • 调用 wx_operation_destroy() 销毁 operation 对象。

wx_error_t wx_operation_wait(wx_operation_t operation, uint32_t timeout_ms);

参数

属性	类型	说明
operation	wx_operation_t	想要等待的 operation 对象
timeout_ms	uint32_t	超时时间，单位毫秒。设置为 0 表示不超时。

返回值

wx_error_t wait 的结果

错误码	说明
WXERROR_OK	接口调用正常完成，operation 对象会被自动释放。
WXERROR_TIMEOUT	operation 超时。
其他	接口调用异常返回错误，operation 对象会被自动释放。

2. 异步等待

异步等待，不会阻塞当前线程。异步操作的结果将通过 callback 函数通知。wx_operation_t 对象将会被自动释放。

void wx_operation_await(wx_operation_t operation,
                        wx_operation_callback_t callback,
                        void* user_data);

参数

属性	类型	说明
operation	wx_operation_t	想要等待的 operation 对象
callback	wx_operation_callback_t	回调函数
user_data	void*	想要在回调函数里接收的自定义数据。

3. 取消异步操作

取消异步操作，wx_operation_t 对象会被释放。调用该函数之后，不应该再对 wx_operation_t 对象执行任何操作。

wx_error_t wx_operation_cancel(wx_operation_t operation);

参数

属性	类型	说明
operation	wx_operation_t	想要取消的 operation 对象

返回值

wx_error_t cancel 的结果

4. 释放对象

主动释放 wx_operation_t 对象，但不会取消异步操作本身。调用该函数之后，不应该再对 operation 对象执行任何操作。

• 如果没有对 wx_operation_t 对象调用 wait 或 cancel 函数，且不关心异步操作的结果，可以调用此函数手动释放 wx_operation_t 对象。
• 当调用 wx_operation_wait() 函数返回 WXERROR_TIMEOUT，如果不希望继续等待，可以调用此函数来释放 wx_operation_t 对象。
• 其他情况下 wx_operation_t 对象会被自动释放，不应该再调用此函数主动释放。

void wx_operation_destroy(wx_operation_t operation);

参数

属性	类型	说明
operation	wx_operation_t	想要释放的 operation 对象