|
3 | 3 | Asynchronous Operations |
4 | 4 | ======================= |
5 | 5 |
|
6 | | -The SDK provides a thread-safe, asynchronous, and reentrant public API. This means that these public API methods can return results produced asynchronously in the form of :cpp:type:`async_result <dolbyio::comms::async_result>`. The :cpp:type:`async_result <dolbyio::comms::async_result>` object represents an eventual completion or a failure of an asynchronous operation and its resulting value. All calls to the SDK are queued onto the SDKs event loop and processed in the FIFO (First In, First Out) order. After making a call, the SDK user application is responsible for either blocking until the operation completes and result is available or setting a function object to execute when the asynchronous operation resolves using the :cpp:class:`async_result and <dolbyio::comms::detail::async_result>` methods. We highly recommend the latter to fully utilize the asynchronous capabilities of the SDK. |
| 6 | +The SDK provides a thread-safe, asynchronous, and reentrant public API. This means that these public API methods can return results produced asynchronously |
| 7 | +in the form of :cpp:type:`async_result <dolbyio::comms::async_result>`. The :cpp:type:`async_result <dolbyio::comms::async_result>` object represents |
| 8 | +an eventual completion or a failure of an asynchronous operation and its resulting value. All calls to the SDK are queued onto the SDKs event loop |
| 9 | +and processed in the FIFO (First In, First Out) order. After making a call, the SDK user application is responsible for either blocking the :cpp:func:`wait <dolbyio::comms::wait>` |
| 10 | +results or setting a function object execute when the asynchronous operation returns using the |
| 11 | +:cpp:class:`async_result and <dolbyio::comms::detail::async_result>` methods. |
7 | 12 |
|
8 | 13 | When a user application invokes an asynchronous method of the SDK, the SDK creates two objects: :cpp:type:`solver <dolbyio::comms::solver>`, |
9 | | -which is used by the asynchronous operation to notify about its completion, and :cpp:type:`async_result <dolbyio::comms::async_result>`, which is used by the application to get the completion notifications. Both of these objects share the same internal state. The user application must set function object callbacks to be executed when the operation succeeds or fails on the async_result. When the asynchronous operation completes the callbacks set by the user, it invokes the application. |
| 14 | +which is used by the asynchronous operation to notify about its completion, and :cpp:type:`async_result <dolbyio::comms::async_result>`, which is used by the application to get the completion notifications. Both of these objects share the same internal state. The user application must set function |
| 15 | +object callbacks to be executed when the operation succeeds or fails on the async_result. If the :cpp:func:`wait <dolbyio::comms::wait>` helper is used, |
| 16 | +this is done automatically. When the asynchronous operation completes the callbacks set by the user, it invokes the application. |
10 | 17 | If the asynchronous operation ends before the callbacks are set by the user application, then the callbacks are invoked as soon as they are |
11 | 18 | set, on the application's thread. Otherwise, the callbacks are invoked when the operation is finished on the SDK's event loop. |
12 | 19 |
|
@@ -40,6 +47,7 @@ sections below. The helper method allows for synchronous usage of the asynchrono |
40 | 47 | .. doxygenfunction:: dolbyio::comms::wait |
41 | 48 | :project: C++ SDK |
42 | 49 |
|
| 50 | + |
43 | 51 | .. _async_resultt: |
44 | 52 |
|
45 | 53 | Async Result Class |
|
0 commit comments